@punks/cli 0.1.16 → 1.0.0

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

@@ -0,0 +1,291 @@
+# TypeScript Patterns for TanStack Query
+
+**Type-safe query and mutation patterns**
+
+---
+
+## 1. Basic Type Inference
+
+```tsx
+type Todo = {
+  id: number
+  title: string
+  completed: boolean
+}
+
+// ✅ Automatic type inference
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async (): Promise<Todo[]> => {
+    const response = await fetch('/api/todos')
+    return response.json()
+  },
+})
+// data is typed as Todo[] | undefined
+```
+
+---
+
+## 2. Generic Query Hook
+
+```tsx
+function useEntity<T>(
+  endpoint: string,
+  id: number
+) {
+  return useQuery({
+    queryKey: [endpoint, id],
+    queryFn: async (): Promise<T> => {
+      const response = await fetch(`/api/${endpoint}/${id}`)
+      return response.json()
+    },
+  })
+}
+
+// Usage
+const { data } = useEntity<User>('users', 1)
+// data: User | undefined
+```
+
+---
+
+## 3. queryOptions with Type Safety
+
+```tsx
+export const todosQueryOptions = queryOptions({
+  queryKey: ['todos'],
+  queryFn: async (): Promise<Todo[]> => {
+    const response = await fetch('/api/todos')
+    return response.json()
+  },
+  staleTime: 1000 * 60,
+})
+
+// Perfect type inference everywhere
+useQuery(todosQueryOptions)
+useSuspenseQuery(todosQueryOptions)
+queryClient.prefetchQuery(todosQueryOptions)
+```
+
+---
+
+## 4. Mutation with Types
+
+```tsx
+type CreateTodoInput = {
+  title: string
+}
+
+type CreateTodoResponse = Todo
+
+const { mutate } = useMutation<
+  CreateTodoResponse, // TData
+  Error, // TError
+  CreateTodoInput, // TVariables
+  { previous?: Todo[] } // TContext
+>({
+  mutationFn: async (input) => {
+    const response = await fetch('/api/todos', {
+      method: 'POST',
+      body: JSON.stringify(input),
+    })
+    return response.json()
+  },
+})
+
+// Type-safe mutation
+mutate({ title: 'New todo' })
+```
+
+---
+
+## 5. Custom Error Types
+
+```tsx
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code: string
+  ) {
+    super(message)
+  }
+}
+
+const { data, error } = useQuery<Todo[], ApiError>({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    if (!response.ok) {
+      throw new ApiError(
+        'Failed to fetch',
+        response.status,
+        'FETCH_ERROR'
+      )
+    }
+    return response.json()
+  },
+})
+
+if (error) {
+  // error.status and error.code are typed
+}
+```
+
+---
+
+## 6. Zod Schema Validation
+
+```tsx
+import { z } from 'zod'
+
+const TodoSchema = z.object({
+  id: z.number(),
+  title: z.string(),
+  completed: z.boolean(),
+})
+
+type Todo = z.infer<typeof TodoSchema>
+
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    const json = await response.json()
+    return TodoSchema.array().parse(json) // Runtime + compile time safety
+  },
+})
+```
+
+---
+
+## 7. Discriminated Union for Status
+
+```tsx
+type QueryState<T> =
+  | { status: 'pending'; data: undefined; error: null }
+  | { status: 'error'; data: undefined; error: Error }
+  | { status: 'success'; data: T; error: null }
+
+function useTypedQuery<T>(
+  queryKey: string[],
+  queryFn: () => Promise<T>
+): QueryState<T> {
+  const { data, status, error } = useQuery({ queryKey, queryFn })
+
+  return {
+    status,
+    data: data as any,
+    error: error as any,
+  }
+}
+
+// Usage with exhaustive checking
+const result = useTypedQuery(['todos'], fetchTodos)
+
+switch (result.status) {
+  case 'pending':
+    return <Loading />
+  case 'error':
+    return <Error error={result.error} /> // error is typed
+  case 'success':
+    return <TodoList todos={result.data} /> // data is typed
+}
+```
+
+---
+
+## 8. Type-Safe Query Keys
+
+```tsx
+// Define all query keys in one place
+const queryKeys = {
+  todos: {
+    all: ['todos'] as const,
+    lists: () => [...queryKeys.todos.all, 'list'] as const,
+    list: (filters: TodoFilters) =>
+      [...queryKeys.todos.lists(), filters] as const,
+    details: () => [...queryKeys.todos.all, 'detail'] as const,
+    detail: (id: number) =>
+      [...queryKeys.todos.details(), id] as const,
+  },
+}
+
+// Usage
+useQuery({
+  queryKey: queryKeys.todos.detail(1),
+  queryFn: () => fetchTodo(1),
+})
+
+queryClient.invalidateQueries({
+  queryKey: queryKeys.todos.all
+})
+```
+
+---
+
+## 9. Utility Types
+
+```tsx
+import type { UseQueryResult, UseMutationResult } from '@tanstack/react-query'
+
+// Extract query data type
+type TodosQuery = UseQueryResult<Todo[]>
+type TodoData = TodosQuery['data'] // Todo[] | undefined
+
+// Extract mutation types
+type AddTodoMutation = UseMutationResult<
+  Todo,
+  Error,
+  CreateTodoInput
+>
+```
+
+---
+
+## 10. Strict Null Checks
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['todo', id],
+  queryFn: () => fetchTodo(id),
+})
+
+// ❌ TypeScript error if strictNullChecks enabled
+const title = data.title
+
+// ✅ Proper null handling
+const title = data?.title ?? 'No title'
+
+// ✅ Type guard
+if (data) {
+  const title = data.title // data is Todo, not undefined
+}
+```
+
+---
+
+## 11. SuspenseQuery Types
+
+```tsx
+const { data } = useSuspenseQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+})
+
+// data is ALWAYS Todo[], never undefined
+// No need for undefined checks with suspense
+data.map(todo => todo.title) // ✅ Safe
+```
+
+---
+
+## Best Practices
+
+✅ Always type queryFn return value
+✅ Use const assertions for query keys
+✅ Leverage queryOptions for reusability
+✅ Use Zod for runtime + compile time validation
+✅ Enable strict null checks
+✅ Create type-safe query key factories
+✅ Use custom error types for better error handling

package/dist/skills/frameworks/tanstack-query/tanstack-query/references/v4-to-v5-migration.md

@@ -0,0 +1,231 @@
+# TanStack Query v4 to v5 Migration Guide
+
+**Complete migration checklist for upgrading from React Query v4 to TanStack Query v5**
+
+---
+
+## Breaking Changes Summary
+
+### 1. Object Syntax Required ⚠️
+
+**v4** allowed multiple signatures:
+```tsx
+useQuery(['todos'], fetchTodos, { staleTime: 5000 })
+useQuery(['todos'], fetchTodos)
+useQuery(queryOptions)
+```
+
+**v5** only supports object syntax:
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000
+})
+```
+
+**Migration**: Use codemod or manual update
+```bash
+npx @tanstack/react-query-codemod v5/remove-overloads
+```
+
+### 2. Query Callbacks Removed ⚠️
+
+**Removed from queries** (still work in mutations):
+- `onSuccess`
+- `onError`
+- `onSettled`
+
+**v4**:
+```tsx
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  onSuccess: (data) => console.log(data) // ❌ Removed
+})
+```
+
+**v5** - Use `useEffect`:
+```tsx
+const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+
+useEffect(() => {
+  if (data) {
+    console.log(data)
+  }
+}, [data])
+```
+
+**Mutation callbacks still work**:
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onSuccess: () => {} // ✅ Still works
+})
+```
+
+### 3. `isLoading` → `isPending` ⚠️
+
+**v4**: `isLoading` meant "no data yet"
+**v5**: `isPending` means "no data yet", `isLoading` = `isPending && isFetching`
+
+```tsx
+// v4
+const { data, isLoading } = useQuery(...)
+if (isLoading) return <Loading />
+
+// v5
+const { data, isPending } = useQuery(...)
+if (isPending) return <Loading />
+```
+
+### 4. `cacheTime` → `gcTime` ⚠️
+
+```tsx
+// v4
+cacheTime: 1000 * 60 * 60
+
+// v5
+gcTime: 1000 * 60 * 60
+```
+
+### 5. `initialPageParam` Required for Infinite Queries ⚠️
+
+```tsx
+// v4
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam = 0 }) => fetchProjects(pageParam),
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+
+// v5
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0, // ✅ Required
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+```
+
+### 6. `keepPreviousData` → `placeholderData` ⚠️
+
+```tsx
+// v4
+keepPreviousData: true
+
+// v5
+import { keepPreviousData } from '@tanstack/react-query'
+
+placeholderData: keepPreviousData
+```
+
+### 7. `useErrorBoundary` → `throwOnError` ⚠️
+
+```tsx
+// v4
+useErrorBoundary: true
+
+// v5
+throwOnError: true
+
+// Or conditional:
+throwOnError: (error) => error.status >= 500
+```
+
+### 8. Error Type Default Changed
+
+**v4**: `error: unknown`
+**v5**: `error: Error`
+
+If throwing non-Error types:
+```tsx
+const { error } = useQuery<DataType, string>({
+  queryKey: ['data'],
+  queryFn: async () => {
+    if (fail) throw 'custom string error'
+    return data
+  },
+})
+```
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Update Packages
+
+```bash
+npm install @tanstack/react-query@latest
+npm install -D @tanstack/react-query-devtools@latest
+```
+
+### Step 2: Run Codemods
+
+```bash
+# Remove function overloads
+npx @tanstack/react-query-codemod v5/remove-overloads
+
+# Replace removed/renamed methods
+npx @tanstack/react-query-codemod v5/rename-properties
+```
+
+### Step 3: Manual Fixes
+
+1. Replace query callbacks with useEffect
+2. Replace `isLoading` with `isPending`
+3. Replace `cacheTime` with `gcTime`
+4. Add `initialPageParam` to infinite queries
+5. Replace `keepPreviousData` with `placeholderData`
+
+### Step 4: TypeScript Fixes
+
+Update type imports:
+```tsx
+// v4
+import type { UseQueryResult } from 'react-query'
+
+// v5
+import type { UseQueryResult } from '@tanstack/react-query'
+```
+
+### Step 5: Test Thoroughly
+
+- Check all queries work
+- Verify mutations invalidate correctly
+- Test error handling
+- Check infinite queries
+- Verify TypeScript types
+
+---
+
+## Common Migration Issues
+
+### Issue: Callbacks not firing
+**Cause**: Query callbacks removed
+**Fix**: Use useEffect or move to mutations
+
+### Issue: isLoading always false
+**Cause**: Meaning changed
+**Fix**: Use isPending for initial load
+
+### Issue: cacheTime not recognized
+**Cause**: Renamed
+**Fix**: Use gcTime
+
+### Issue: infinite query type error
+**Cause**: initialPageParam required
+**Fix**: Add initialPageParam
+
+---
+
+## Full Codemod List
+
+```bash
+# All v5 codemods
+npx @tanstack/react-query-codemod v5/remove-overloads
+npx @tanstack/react-query-codemod v5/rename-properties
+npx @tanstack/react-query-codemod v5/replace-imports
+```
+
+**Note**: Codemods may not catch everything - manual review required!

package/dist/skills/frameworks/tanstack-query/tanstack-query/rules/tanstack-query.md

@@ -0,0 +1,126 @@
+---
+paths: "**/*.tsx", "**/*.ts", "**/*query*.ts", "**/*hook*.ts"
+---
+
+# TanStack Query v5 Corrections
+
+Claude's training may reference TanStack Query v4 patterns. This project uses **v5**.
+
+## Object Syntax Required
+
+```typescript
+/* ❌ v4 array syntax (removed in v5) */
+useQuery(['todos'], fetchTodos, { staleTime: 5000 })
+
+/* ✅ v5 object syntax only */
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 5000
+})
+```
+
+## Query Callbacks Removed
+
+```typescript
+/* ❌ v5 removed onSuccess/onError/onSettled from queries */
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  onSuccess: (data) => console.log(data), // Removed!
+})
+
+/* ✅ Use useEffect instead */
+const { data } = useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+useEffect(() => {
+  if (data) console.log(data)
+}, [data])
+
+/* Note: Mutations still support callbacks */
+useMutation({
+  mutationFn: addTodo,
+  onSuccess: () => {}, // Still works!
+})
+```
+
+## isPending vs isLoading
+
+```typescript
+/* ❌ isLoading meaning changed in v5 */
+if (isLoading) return <Loading />
+
+/* ✅ Use isPending for initial load */
+const { data, isPending } = useQuery(...)
+if (isPending) return <Loading />
+// isPending = no data yet
+// isLoading = isPending && isFetching
+```
+
+## cacheTime → gcTime
+
+```typescript
+/* ❌ Renamed in v5 */
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  cacheTime: 1000 * 60 * 60, // Error!
+})
+
+/* ✅ Use gcTime */
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  gcTime: 1000 * 60 * 60,
+})
+```
+
+## keepPreviousData → placeholderData
+
+```typescript
+/* ❌ Removed in v5 */
+useQuery({
+  queryKey: ['todos', page],
+  queryFn: () => fetchTodos(page),
+  keepPreviousData: true, // Error!
+})
+
+/* ✅ Use placeholderData helper */
+import { keepPreviousData } from '@tanstack/react-query'
+
+useQuery({
+  queryKey: ['todos', page],
+  queryFn: () => fetchTodos(page),
+  placeholderData: keepPreviousData,
+})
+```
+
+## Infinite Queries: initialPageParam Required
+
+```typescript
+/* ❌ v4 used undefined as first pageParam */
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam = 0 }) => fetchProjects(pageParam),
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+
+/* ✅ v5 requires explicit initialPageParam */
+useInfiniteQuery({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0, // Required!
+  getNextPageParam: (lastPage) => lastPage.nextCursor,
+})
+```
+
+## Quick Fixes
+
+| If Claude suggests... | Use instead... |
+|----------------------|----------------|
+| `useQuery(['key'], fn, opts)` | `useQuery({ queryKey, queryFn, ...opts })` |
+| `onSuccess` in useQuery | `useEffect` watching data |
+| `cacheTime` | `gcTime` |
+| `isLoading` for initial load | `isPending` |
+| `keepPreviousData: true` | `placeholderData: keepPreviousData` |
+| Missing `initialPageParam` | Add `initialPageParam: 0` (or appropriate value) |
+| `useErrorBoundary` | `throwOnError` |

package/dist/skills/frameworks/tanstack-query/tanstack-query/scripts/example-script.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# [TODO: Script Name]
+# [TODO: Brief description of what this script does]
+
+# Example script structure - delete if not needed
+
+set -e  # Exit on error
+
+# [TODO: Add your script logic here]
+
+echo "Example script - replace or delete this file"
+
+# Usage:
+# ./scripts/example-script.sh [args]