@smicolon/ai-kit 0.3.2 → 0.4.0

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

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

@@ -1,359 +0,0 @@
----
-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 })
-```