@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/tanstack-query/tanstack-query/assets/example-template.txt

@@ -0,0 +1,14 @@
+[TODO: Example Template File]
+
+[TODO: This directory contains files that will be used in the OUTPUT that Claude produces.]
+
+[TODO: Examples:]
+- Templates (.html, .tsx, .md)
+- Images (.png, .svg)
+- Fonts (.ttf, .woff)
+- Boilerplate code
+- Configuration file templates
+
+[TODO: Delete this file and add your actual assets]
+
+These files are NOT loaded into context. They are copied or used directly in the final output.

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/best-practices.md

@@ -0,0 +1,304 @@
+# TanStack Query Best Practices
+
+**Performance, caching strategies, and common patterns**
+
+---
+
+## 1. Avoid Request Waterfalls
+
+### ❌ Bad: Sequential Dependencies
+
+```tsx
+function BadUserProfile({ userId }) {
+  const { data: user } = useQuery({
+    queryKey: ['users', userId],
+    queryFn: () => fetchUser(userId),
+  })
+
+  // Waits for user ⏳
+  const { data: posts } = useQuery({
+    queryKey: ['posts', user?.id],
+    queryFn: () => fetchPosts(user!.id),
+    enabled: !!user,
+  })
+
+  // Waits for posts ⏳⏳
+  const { data: comments } = useQuery({
+    queryKey: ['comments', posts?.[0]?.id],
+    queryFn: () => fetchComments(posts![0].id),
+    enabled: !!posts && posts.length > 0,
+  })
+}
+```
+
+### ✅ Good: Parallel Queries
+
+```tsx
+function GoodUserProfile({ userId }) {
+  // All run in parallel 🚀
+  const { data: user } = useQuery({
+    queryKey: ['users', userId],
+    queryFn: () => fetchUser(userId),
+  })
+
+  const { data: posts } = useQuery({
+    queryKey: ['posts', userId], // Use userId, not user.id
+    queryFn: () => fetchPosts(userId),
+  })
+
+  const { data: comments } = useQuery({
+    queryKey: ['comments', userId],
+    queryFn: () => fetchUserComments(userId),
+  })
+}
+```
+
+---
+
+## 2. Query Key Strategy
+
+### Hierarchical Structure
+
+```tsx
+// Global
+['todos'] // All todos
+['todos', { status: 'done' }] // Filtered todos
+['todos', 123] // Single todo
+
+// Invalidation hierarchy
+queryClient.invalidateQueries({ queryKey: ['todos'] }) // Invalidates ALL todos
+queryClient.invalidateQueries({ queryKey: ['todos', { status: 'done' }] }) // Only filtered
+```
+
+### Best Practices
+
+```tsx
+// ✅ Good: Stable, serializable keys
+['users', userId, { sort: 'name', filter: 'active' }]
+
+// ❌ Bad: Functions in keys (not serializable)
+['users', () => userId]
+
+// ❌ Bad: Changing order
+['users', { filter: 'active', sort: 'name' }] // Different key!
+
+// ✅ Good: Consistent ordering
+const userFilters = { filter: 'active', sort: 'name' }
+```
+
+---
+
+## 3. Caching Configuration
+
+### staleTime vs gcTime
+
+```tsx
+/**
+ * staleTime: How long data is "fresh" (won't refetch)
+ * gcTime: How long unused data stays in cache
+ */
+
+// Real-time data
+staleTime: 0 // Always stale, refetch frequently
+gcTime: 1000 * 60 * 5 // 5 min in cache
+
+// Stable data
+staleTime: 1000 * 60 * 60 // 1 hour fresh
+gcTime: 1000 * 60 * 60 * 24 // 24 hours in cache
+
+// Static data
+staleTime: Infinity // Never stale
+gcTime: Infinity // Never garbage collect
+```
+
+### Per-Query vs Global
+
+```tsx
+// Global defaults
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,
+      gcTime: 1000 * 60 * 60,
+    },
+  },
+})
+
+// Override per query
+useQuery({
+  queryKey: ['stock-price'],
+  queryFn: fetchStockPrice,
+  staleTime: 0, // Override: always stale
+  refetchInterval: 1000 * 30, // Refetch every 30s
+})
+```
+
+---
+
+## 4. Use queryOptions Factory
+
+```tsx
+// ✅ Best practice: Reusable options
+export const todosQueryOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 1000 * 60,
+})
+
+// Use everywhere
+useQuery(todosQueryOptions)
+useSuspenseQuery(todosQueryOptions)
+queryClient.prefetchQuery(todosQueryOptions)
+
+// ❌ Bad: Duplicated configuration
+useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+useSuspenseQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+```
+
+---
+
+## 5. Data Transformations
+
+### select Option
+
+```tsx
+// Only re-render when count changes
+function TodoCount() {
+  const { data: count } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: (data) => data.length, // Transform
+  })
+}
+
+// Cache full data, component gets filtered
+function CompletedTodos() {
+  const { data } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+    select: (data) => data.filter(todo => todo.completed),
+  })
+}
+```
+
+---
+
+## 6. Prefetching
+
+```tsx
+function TodoList() {
+  const queryClient = useQueryClient()
+  const { data: todos } = useTodos()
+
+  const prefetch = (id: number) => {
+    queryClient.prefetchQuery({
+      queryKey: ['todos', id],
+      queryFn: () => fetchTodo(id),
+      staleTime: 1000 * 60 * 5,
+    })
+  }
+
+  return (
+    <ul>
+      {todos.map(todo => (
+        <li key={todo.id} onMouseEnter={() => prefetch(todo.id)}>
+          <Link to={`/todos/${todo.id}`}>{todo.title}</Link>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+---
+
+## 7. Optimistic Updates
+
+Use for:
+- ✅ Low-risk actions (toggle, like)
+- ✅ Frequent actions (better UX)
+
+Avoid for:
+- ❌ Critical operations (payments)
+- ❌ Complex validations
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previous = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    return { previous }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos'], context.previous)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+---
+
+## 8. Error Handling Strategy
+
+### Local vs Global
+
+```tsx
+// Local: Handle in component
+const { data, error, isError } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+if (isError) return <div>Error: {error.message}</div>
+
+// Global: Error boundaries
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  throwOnError: true, // Throw to boundary
+})
+
+// Conditional: Mix both
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  throwOnError: (error) => error.status >= 500, // Only 5xx to boundary
+})
+```
+
+---
+
+## 9. Server State vs Client State
+
+```tsx
+// ❌ Don't use TanStack Query for client state
+const { data: isModalOpen } = useMutation(...)
+
+// ✅ Use useState for client state
+const [isModalOpen, setIsModalOpen] = useState(false)
+
+// ✅ Use TanStack Query for server state only
+const { data: todos } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+```
+
+---
+
+## 10. Performance Monitoring
+
+### Use DevTools
+
+- Check refetch frequency
+- Verify cache hits
+- Monitor query states
+- Export state for debugging
+
+### Key Metrics
+
+- Time to first data
+- Cache hit rate
+- Refetch frequency
+- Network requests count

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/common-patterns.md

@@ -0,0 +1,271 @@
+# Common TanStack Query Patterns
+
+**Reusable patterns for real-world applications**
+
+---
+
+## Pattern 1: Dependent Queries
+
+Query B depends on data from Query A:
+
+```tsx
+function UserPosts({ userId }) {
+  const { data: user } = useQuery({
+    queryKey: ['users', userId],
+    queryFn: () => fetchUser(userId),
+  })
+
+  const { data: posts } = useQuery({
+    queryKey: ['users', userId, 'posts'],
+    queryFn: () => fetchUserPosts(userId),
+    enabled: !!user, // Wait for user
+  })
+}
+```
+
+---
+
+## Pattern 2: Parallel Queries with useQueries
+
+Fetch multiple resources in parallel:
+
+```tsx
+function TodoDetails({ ids }) {
+  const results = useQueries({
+    queries: ids.map(id => ({
+      queryKey: ['todos', id],
+      queryFn: () => fetchTodo(id),
+    })),
+  })
+
+  const isLoading = results.some(r => r.isPending)
+  const data = results.map(r => r.data)
+}
+```
+
+---
+
+## Pattern 3: Paginated Queries with placeholderData
+
+Keep previous data while fetching next page:
+
+```tsx
+import { keepPreviousData } from '@tanstack/react-query'
+
+function PaginatedTodos() {
+  const [page, setPage] = useState(0)
+
+  const { data } = useQuery({
+    queryKey: ['todos', page],
+    queryFn: () => fetchTodos(page),
+    placeholderData: keepPreviousData, // Keep old data while loading
+  })
+}
+```
+
+---
+
+## Pattern 4: Infinite Scroll
+
+Auto-load more data on scroll:
+
+```tsx
+function InfiniteList() {
+  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
+    queryKey: ['items'],
+    queryFn: ({ pageParam }) => fetchItems(pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
+  })
+
+  // Intersection Observer for auto-loading
+  const ref = useRef()
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      ([entry]) => entry.isIntersecting && hasNextPage && fetchNextPage()
+    )
+    if (ref.current) observer.observe(ref.current)
+    return () => observer.disconnect()
+  }, [fetchNextPage, hasNextPage])
+
+  return (
+    <>
+      {data.pages.map(page => page.data.map(item => <div>{item}</div>))}
+      <div ref={ref}>Loading...</div>
+    </>
+  )
+}
+```
+
+---
+
+## Pattern 5: Optimistic Updates
+
+Instant UI feedback:
+
+```tsx
+function useOptimisticToggle() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: updateTodo,
+    onMutate: async (updated) => {
+      await queryClient.cancelQueries({ queryKey: ['todos'] })
+      const previous = queryClient.getQueryData(['todos'])
+
+      queryClient.setQueryData(['todos'], (old) =>
+        old.map(todo => todo.id === updated.id ? updated : todo)
+      )
+
+      return { previous }
+    },
+    onError: (err, vars, context) => {
+      queryClient.setQueryData(['todos'], context.previous)
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+}
+```
+
+---
+
+## Pattern 6: Prefetching on Hover
+
+Load data before user clicks:
+
+```tsx
+function TodoList() {
+  const queryClient = useQueryClient()
+
+  const prefetch = (id) => {
+    queryClient.prefetchQuery({
+      queryKey: ['todos', id],
+      queryFn: () => fetchTodo(id),
+    })
+  }
+
+  return (
+    <ul>
+      {todos.map(todo => (
+        <li onMouseEnter={() => prefetch(todo.id)}>
+          <Link to={`/todos/${todo.id}`}>{todo.title}</Link>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+---
+
+## Pattern 7: Search/Debounce
+
+Debounced search with automatic cancellation:
+
+```tsx
+import { useState, useDeferredValue } from 'react'
+
+function Search() {
+  const [search, setSearch] = useState('')
+  const deferredSearch = useDeferredValue(search)
+
+  const { data } = useQuery({
+    queryKey: ['search', deferredSearch],
+    queryFn: ({ signal }) =>
+      fetch(`/api/search?q=${deferredSearch}`, { signal }).then(r => r.json()),
+    enabled: deferredSearch.length >= 2,
+  })
+}
+```
+
+---
+
+## Pattern 8: Polling/Refetch Interval
+
+Auto-refetch every N seconds:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['stock-price'],
+  queryFn: fetchStockPrice,
+  refetchInterval: 1000 * 30, // Every 30 seconds
+  refetchIntervalInBackground: true, // Even when tab inactive
+})
+```
+
+---
+
+## Pattern 9: Conditional Fetching
+
+Only fetch when needed:
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['user', userId],
+  queryFn: () => fetchUser(userId),
+  enabled: !!userId && isAuthenticated,
+})
+```
+
+---
+
+## Pattern 10: Initial Data from Cache
+
+Use cached data as initial value:
+
+```tsx
+const { data: todo } = useQuery({
+  queryKey: ['todos', id],
+  queryFn: () => fetchTodo(id),
+  initialData: () => {
+    return queryClient
+      .getQueryData(['todos'])
+      ?.find(t => t.id === id)
+  },
+})
+```
+
+---
+
+## Pattern 11: Mutation with Multiple Invalidations
+
+Update multiple related queries:
+
+```tsx
+useMutation({
+  mutationFn: updateTodo,
+  onSuccess: (updated) => {
+    queryClient.setQueryData(['todos', updated.id], updated)
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.invalidateQueries({ queryKey: ['stats'] })
+    queryClient.invalidateQueries({ queryKey: ['users', updated.userId] })
+  },
+})
+```
+
+---
+
+## Pattern 12: Global Error Handler
+
+Centralized error handling:
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      onError: (error) => {
+        toast.error(error.message)
+        logToSentry(error)
+      },
+    },
+    mutations: {
+      onError: (error) => {
+        toast.error('Action failed')
+        logToSentry(error)
+      },
+    },
+  },
+})
+```

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/example-reference.md

@@ -0,0 +1,26 @@
+# [TODO: Reference Document Name]
+
+[TODO: This file contains reference documentation that Claude can load when needed.]
+
+[TODO: Delete this file if you don't have reference documentation to provide.]
+
+## Purpose
+
+[TODO: Explain what information this document contains]
+
+## When Claude Should Use This
+
+[TODO: Describe specific scenarios where Claude should load this reference]
+
+## Content
+
+[TODO: Add your reference content here - schemas, guides, specifications, etc.]
+
+---
+
+**Note**: This file is NOT loaded into context by default. Claude will only load it when:
+- It determines the information is needed
+- You explicitly ask Claude to reference it
+- The SKILL.md instructions direct Claude to read it
+
+Keep this file under 10k words for best performance.