@smicolon/ai-kit 0.1.0 → 0.1.1

package/packs/tanstack-router/skills/pacer-patterns/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: TanStack Pacer Patterns (Beta)
+description: >-
+  TanStack Pacer patterns for rate limiting, debouncing, and throttling.
+  Activates when implementing search inputs, API rate limiting, or
+  performance optimization. NOTE: Beta library - API may change.
+version: 1.0.0
+---
+
+# TanStack Pacer Patterns (Beta)
+
+> **Beta Library**: TanStack Pacer is in beta. APIs may change between versions.
+
+TanStack Pacer provides utilities for rate limiting, debouncing, throttling, and async queuing.
+
+## Debounce
+
+Delay execution until input stops for a specified time.
+
+### Basic Debounce
+```typescript
+import { debounce } from '@tanstack/pacer'
+
+const debouncedSearch = debounce((query: string) => {
+  console.log('Searching:', query)
+  return fetch(`/api/search?q=${query}`)
+}, 300)
+
+// Only executes after 300ms of no calls
+debouncedSearch('h')
+debouncedSearch('he')
+debouncedSearch('hel')
+debouncedSearch('hell')
+debouncedSearch('hello') // Only this executes
+```
+
+### Debounce in React
+```typescript
+import { useDebounce } from '@tanstack/pacer-react'
+import { useState } from 'react'
+
+function SearchInput() {
+  const [query, setQuery] = useState('')
+
+  const debouncedQuery = useDebounce(query, 300)
+
+  // Use debouncedQuery for API calls
+  const { data } = useQuery({
+    queryKey: ['search', debouncedQuery],
+    queryFn: () => searchApi.search(debouncedQuery),
+    enabled: debouncedQuery.length > 0,
+  })
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search..."
+      />
+      {data && <SearchResults results={data} />}
+    </div>
+  )
+}
+```
+
+### Debounced Callback
+```typescript
+import { useDebouncedCallback } from '@tanstack/pacer-react'
+
+function AutoSaveEditor({ postId }: { postId: string }) {
+  const [content, setContent] = useState('')
+  const updatePost = useUpdatePost()
+
+  const saveContent = useDebouncedCallback(
+    async (content: string) => {
+      await updatePost.mutateAsync({ id: postId, content })
+    },
+    1000, // Save after 1s of no typing
+    { maxWait: 5000 } // But at least every 5s
+  )
+
+  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    const newContent = e.target.value
+    setContent(newContent)
+    saveContent(newContent)
+  }
+
+  return (
+    <textarea value={content} onChange={handleChange} />
+  )
+}
+```
+
+## Throttle
+
+Limit execution to at most once per interval.
+
+### Basic Throttle
+```typescript
+import { throttle } from '@tanstack/pacer'
+
+const throttledScroll = throttle((position: number) => {
+  console.log('Scroll position:', position)
+}, 100)
+
+// Executes at most once every 100ms
+window.addEventListener('scroll', () => {
+  throttledScroll(window.scrollY)
+})
+```
+
+### Throttle in React
+```typescript
+import { useThrottledCallback } from '@tanstack/pacer-react'
+import { useEffect } from 'react'
+
+function ScrollTracker() {
+  const trackScroll = useThrottledCallback(
+    (position: number) => {
+      analytics.track('scroll', { position })
+    },
+    500
+  )
+
+  useEffect(() => {
+    const handleScroll = () => trackScroll(window.scrollY)
+    window.addEventListener('scroll', handleScroll)
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [trackScroll])
+
+  return null
+}
+```
+
+### Throttled API Calls
+```typescript
+import { useThrottledCallback } from '@tanstack/pacer-react'
+
+function LiveSearch() {
+  const [results, setResults] = useState<Result[]>([])
+
+  const search = useThrottledCallback(
+    async (query: string) => {
+      const data = await searchApi.search(query)
+      setResults(data)
+    },
+    200, // At most 5 requests per second
+    { leading: true, trailing: true }
+  )
+
+  return (
+    <input
+      onChange={(e) => search(e.target.value)}
+      placeholder="Search..."
+    />
+  )
+}
+```
+
+## Rate Limiting
+
+Control the rate of operations.
+
+### Rate Limiter
+```typescript
+import { createRateLimiter } from '@tanstack/pacer'
+
+const apiLimiter = createRateLimiter({
+  limit: 10,      // 10 requests
+  interval: 1000, // per second
+})
+
+async function fetchData(id: string) {
+  await apiLimiter.acquire() // Wait if rate limited
+  return fetch(`/api/data/${id}`)
+}
+
+// Safe to call rapidly - will be rate limited
+await Promise.all(
+  ids.map(id => fetchData(id))
+)
+```
+
+### Per-Key Rate Limiting
+```typescript
+import { createKeyedRateLimiter } from '@tanstack/pacer'
+
+const userLimiter = createKeyedRateLimiter({
+  limit: 5,
+  interval: 60000, // 5 requests per minute per user
+})
+
+async function handleUserAction(userId: string, action: Action) {
+  const limiter = userLimiter.get(userId)
+  if (!limiter.tryAcquire()) {
+    throw new Error('Rate limited. Please try again later.')
+  }
+  return processAction(action)
+}
+```
+
+## Async Queue
+
+Process async operations sequentially or with concurrency limits.
+
+### Sequential Queue
+```typescript
+import { createAsyncQueue } from '@tanstack/pacer'
+
+const uploadQueue = createAsyncQueue({
+  concurrency: 1, // One at a time
+})
+
+async function uploadFiles(files: File[]) {
+  const results = await Promise.all(
+    files.map(file =>
+      uploadQueue.add(() => uploadFile(file))
+    )
+  )
+  return results
+}
+```
+
+### Concurrent Queue with Limit
+```typescript
+import { createAsyncQueue } from '@tanstack/pacer'
+
+const processQueue = createAsyncQueue({
+  concurrency: 3, // Max 3 concurrent
+})
+
+function ProcessingStatus() {
+  const { pending, active, completed } = processQueue.status
+
+  return (
+    <div>
+      <span>Pending: {pending}</span>
+      <span>Active: {active}</span>
+      <span>Completed: {completed}</span>
+    </div>
+  )
+}
+```
+
+### Queue with Priority
+```typescript
+import { createAsyncQueue } from '@tanstack/pacer'
+
+const taskQueue = createAsyncQueue({
+  concurrency: 2,
+})
+
+// Higher priority tasks run first
+taskQueue.add(() => processTask('low'), { priority: 1 })
+taskQueue.add(() => processTask('high'), { priority: 10 })
+taskQueue.add(() => processTask('urgent'), { priority: 100 })
+```
+
+## Integration with TanStack Query
+
+```typescript
+import { useDebounce } from '@tanstack/pacer-react'
+import { useQuery } from '@tanstack/react-query'
+
+function SearchWithDebounce() {
+  const [input, setInput] = useState('')
+  const debouncedInput = useDebounce(input, 300)
+
+  const { data, isLoading } = useQuery({
+    queryKey: ['search', debouncedInput],
+    queryFn: () => searchApi.search(debouncedInput),
+    enabled: debouncedInput.length >= 2,
+  })
+
+  return (
+    <div>
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        placeholder="Search (min 2 chars)..."
+      />
+      {isLoading && <Spinner />}
+      {data && <Results items={data} />}
+    </div>
+  )
+}
+```
+
+## Common Use Cases
+
+| Scenario | Solution |
+|----------|----------|
+| Search input | Debounce 300ms |
+| Auto-save | Debounce 1s with maxWait |
+| Scroll tracking | Throttle 100-200ms |
+| API rate limits | Rate limiter |
+| File uploads | Async queue with concurrency |
+| Resize handler | Throttle 100ms |
+
+## Conventions
+
+1. **Debounce for inputs** - Always debounce search/filter inputs
+2. **Throttle for events** - Use for scroll, resize, mousemove
+3. **Rate limit APIs** - Protect against abuse
+4. **Queue heavy operations** - Use for file uploads, bulk operations
+5. **Cleanup** - Cancel pending operations on unmount
+
+## Anti-Patterns
+
+```typescript
+// ❌ WRONG: No debounce on search
+function Search() {
+  const [query, setQuery] = useState('')
+  const { data } = useQuery({
+    queryKey: ['search', query], // Fires on every keystroke!
+    queryFn: () => search(query),
+  })
+}
+
+// ✅ CORRECT: Debounced search
+function Search() {
+  const [query, setQuery] = useState('')
+  const debouncedQuery = useDebounce(query, 300)
+  const { data } = useQuery({
+    queryKey: ['search', debouncedQuery],
+    queryFn: () => search(debouncedQuery),
+    enabled: debouncedQuery.length > 0,
+  })
+}
+
+// ❌ WRONG: Creating debounce inside render
+function Component() {
+  const search = debounce(() => {}, 300) // New instance every render!
+}
+
+// ✅ CORRECT: Use hook
+function Component() {
+  const search = useDebouncedCallback(() => {}, 300)
+}
+```

package/packs/tanstack-router/skills/query-patterns/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: TanStack Query Patterns
+description: >-
+  Auto-enforce TanStack Query best practices with factory key pattern. Activates
+  when creating queries, mutations, managing server state, or implementing data
+  fetching in React applications.
+version: 1.0.0
+---
+
+# TanStack Query Patterns
+
+This skill enforces TanStack Query best practices for server state management in React applications.
+
+## Query Key Factory Pattern
+
+The factory pattern provides type-safe, hierarchical query keys:
+
+```typescript
+// lib/query-keys.ts
+export const queryKeys = {
+  posts: {
+    all: () => ['posts'] as const,
+    lists: () => [...queryKeys.posts.all(), 'list'] as const,
+    list: (filters: PostFilters) => [...queryKeys.posts.lists(), filters] as const,
+    details: () => [...queryKeys.posts.all(), 'detail'] as const,
+    detail: (id: string) => [...queryKeys.posts.details(), id] as const,
+    comments: (id: string) => [...queryKeys.posts.detail(id), 'comments'] as const,
+  },
+  users: {
+    all: () => ['users'] as const,
+    detail: (id: string) => [...queryKeys.users.all(), id] as const,
+    profile: () => [...queryKeys.users.all(), 'profile'] as const,
+  },
+  auth: {
+    session: () => ['auth', 'session'] as const,
+  },
+} as const
+```
+
+## Query Options Factory
+
+Define reusable query options for consistency:
+
+```typescript
+// features/posts/queries/postQueries.ts
+import { queryOptions } from '@tanstack/react-query'
+import { queryKeys } from '@/lib/query-keys'
+import { postApi } from '@/features/posts/api'
+
+export const postQueryOptions = (postId: string) =>
+  queryOptions({
+    queryKey: queryKeys.posts.detail(postId),
+    queryFn: () => postApi.getPost(postId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  })
+
+export const postsQueryOptions = (filters: PostFilters = {}) =>
+  queryOptions({
+    queryKey: queryKeys.posts.list(filters),
+    queryFn: () => postApi.getPosts(filters),
+    staleTime: 1 * 60 * 1000, // 1 minute
+  })
+
+export const postCommentsQueryOptions = (postId: string) =>
+  queryOptions({
+    queryKey: queryKeys.posts.comments(postId),
+    queryFn: () => postApi.getPostComments(postId),
+    enabled: Boolean(postId),
+  })
+```
+
+## Query Client Setup
+
+```typescript
+// lib/query-client.ts
+import { QueryClient } from '@tanstack/react-query'
+
+export function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // 1 minute
+        gcTime: 5 * 60 * 1000, // 5 minutes (formerly cacheTime)
+        retry: 1,
+        refetchOnWindowFocus: false,
+      },
+      mutations: {
+        retry: 0,
+      },
+    },
+  })
+}
+```
+
+## Using Queries in Components
+
+### With useSuspenseQuery (Recommended with Router)
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { postQueryOptions } from '@/features/posts/queries'
+
+function PostDetail({ postId }: { postId: string }) {
+  // Data guaranteed by route loader, suspense handles loading
+  const { data: post } = useSuspenseQuery(postQueryOptions(postId))
+
+  return <article>{post.title}</article>
+}
+```
+
+### With useQuery (Manual Loading States)
+```typescript
+import { useQuery } from '@tanstack/react-query'
+import { postsQueryOptions } from '@/features/posts/queries'
+
+function PostList({ filters }: { filters: PostFilters }) {
+  const { data, isLoading, error } = useQuery(postsQueryOptions(filters))
+
+  if (isLoading) return <Skeleton />
+  if (error) return <Error error={error} />
+
+  return (
+    <ul>
+      {data.map(post => (
+        <PostCard key={post.id} post={post} />
+      ))}
+    </ul>
+  )
+}
+```
+
+## Mutations
+
+### Basic Mutation Hook
+```typescript
+// features/posts/hooks/useCreatePost.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { queryKeys } from '@/lib/query-keys'
+import { postApi } from '@/features/posts/api'
+
+export function useCreatePost() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: postApi.createPost,
+    onSuccess: () => {
+      // Invalidate all post lists
+      queryClient.invalidateQueries({ queryKey: queryKeys.posts.lists() })
+    },
+  })
+}
+```
+
+### Optimistic Updates
+```typescript
+// features/posts/hooks/useUpdatePost.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { queryKeys } from '@/lib/query-keys'
+import type { Post, UpdatePostInput } from '@/features/posts/types'
+
+export function useUpdatePost() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: postApi.updatePost,
+    onMutate: async (newPost: UpdatePostInput) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({
+        queryKey: queryKeys.posts.detail(newPost.id)
+      })
+
+      // Snapshot previous value
+      const previous = queryClient.getQueryData<Post>(
+        queryKeys.posts.detail(newPost.id)
+      )
+
+      // Optimistically update
+      queryClient.setQueryData(
+        queryKeys.posts.detail(newPost.id),
+        (old: Post | undefined) => old ? { ...old, ...newPost } : undefined
+      )
+
+      return { previous }
+    },
+    onError: (err, newPost, context) => {
+      // Rollback on error
+      if (context?.previous) {
+        queryClient.setQueryData(
+          queryKeys.posts.detail(newPost.id),
+          context.previous
+        )
+      }
+    },
+    onSettled: (data, error, variables) => {
+      // Always refetch after error or success
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.posts.detail(variables.id)
+      })
+    },
+  })
+}
+```
+
+### Delete with Optimistic Update
+```typescript
+export function useDeletePost() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: postApi.deletePost,
+    onMutate: async (postId: string) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.posts.lists() })
+
+      const previousLists = queryClient.getQueriesData<Post[]>({
+        queryKey: queryKeys.posts.lists()
+      })
+
+      // Remove from all lists optimistically
+      queryClient.setQueriesData<Post[]>(
+        { queryKey: queryKeys.posts.lists() },
+        (old) => old?.filter(post => post.id !== postId)
+      )
+
+      return { previousLists }
+    },
+    onError: (err, postId, context) => {
+      context?.previousLists.forEach(([queryKey, data]) => {
+        queryClient.setQueryData(queryKey, data)
+      })
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.posts.all() })
+    },
+  })
+}
+```
+
+## Prefetching
+
+### In Route Loaders
+```typescript
+// routes/posts.tsx
+export const Route = createFileRoute('/posts')({
+  loader: ({ context: { queryClient } }) =>
+    queryClient.ensureQueryData(postsQueryOptions()),
+})
+```
+
+### On Hover/Focus
+```typescript
+import { useQueryClient } from '@tanstack/react-query'
+import { Link } from '@tanstack/react-router'
+import { postQueryOptions } from '@/features/posts/queries'
+
+function PostLink({ postId, title }: { postId: string; title: string }) {
+  const queryClient = useQueryClient()
+
+  const prefetch = () => {
+    queryClient.prefetchQuery(postQueryOptions(postId))
+  }
+
+  return (
+    <Link
+      to="/posts/$postId"
+      params={{ postId }}
+      onMouseEnter={prefetch}
+      onFocus={prefetch}
+    >
+      {title}
+    </Link>
+  )
+}
+```
+
+## Infinite Queries
+
+```typescript
+import { useInfiniteQuery } from '@tanstack/react-query'
+
+export function useInfinitePosts(filters: PostFilters) {
+  return useInfiniteQuery({
+    queryKey: queryKeys.posts.list({ ...filters, infinite: true }),
+    queryFn: ({ pageParam = 1 }) =>
+      postApi.getPosts({ ...filters, page: pageParam }),
+    getNextPageParam: (lastPage, pages) =>
+      lastPage.hasMore ? pages.length + 1 : undefined,
+    initialPageParam: 1,
+  })
+}
+```
+
+## Dependent Queries
+
+```typescript
+function PostWithAuthor({ postId }: { postId: string }) {
+  const { data: post } = useQuery(postQueryOptions(postId))
+
+  const { data: author } = useQuery({
+    ...userQueryOptions(post?.authorId ?? ''),
+    enabled: Boolean(post?.authorId),
+  })
+
+  if (!post) return <Skeleton />
+
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      {author && <p>By {author.name}</p>}
+    </article>
+  )
+}
+```
+
+## Conventions to Enforce
+
+1. **Factory pattern for keys** - All query keys through `queryKeys` factory
+2. **Query options factories** - Define in `features/*/queries/` directories
+3. **Invalidate by hierarchy** - Use `queryKeys.posts.lists()` to invalidate all lists
+4. **Optimistic updates** - Always include rollback logic
+5. **Enable conditional queries** - Use `enabled` option for dependent queries
+6. **Proper staleTime** - Set based on data freshness requirements
+7. **Use gcTime not cacheTime** - Renamed in v5
+
+## Anti-Patterns to Block
+
+```typescript
+// ❌ WRONG: String query keys
+useQuery({ queryKey: ['posts', postId] })
+
+// ✅ CORRECT: Factory pattern
+useQuery(postQueryOptions(postId))
+
+// ❌ WRONG: Inline query function
+useQuery({
+  queryKey: queryKeys.posts.detail(postId),
+  queryFn: async () => {
+    const res = await fetch(`/api/posts/${postId}`)
+    return res.json()
+  }
+})
+
+// ✅ CORRECT: Extracted to API layer
+useQuery(postQueryOptions(postId))
+
+// ❌ WRONG: Manual cache updates without invalidation
+onSuccess: (newPost) => {
+  queryClient.setQueryData(['posts', newPost.id], newPost)
+}
+
+// ✅ CORRECT: Invalidate to refetch
+onSuccess: () => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.posts.all() })
+}
+
+// ❌ WRONG: Using cacheTime (deprecated)
+useQuery({ cacheTime: 5000 })
+
+// ✅ CORRECT: Use gcTime
+useQuery({ gcTime: 5000 })
+```