@smicolon/ai-kit 0.3.2 → 0.4.1

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

@@ -1,285 +0,0 @@
----
-name: TanStack Router Patterns
-description: >-
-  Auto-enforce TanStack Router file-based routing conventions. Activates when
-  creating routes, configuring navigation, handling route params, or working
-  with search params in React SPA applications.
-version: 1.0.0
----
-
-# TanStack Router Patterns
-
-This skill enforces TanStack Router best practices for file-based routing in React SPA applications.
-
-## Route File Naming Conventions
-
-| Pattern | Example | URL Path | Purpose |
-|---------|---------|----------|---------|
-| `__root.tsx` | `routes/__root.tsx` | - | Root layout, wraps all routes |
-| `index.tsx` | `routes/index.tsx` | `/` | Index route |
-| `about.tsx` | `routes/about.tsx` | `/about` | Static segment |
-| `posts.tsx` | `routes/posts.tsx` | `/posts` | Layout route (has `<Outlet />`) |
-| `posts.index.tsx` | `routes/posts.index.tsx` | `/posts` | Posts index (nested in layout) |
-| `posts.$postId.tsx` | `routes/posts.$postId.tsx` | `/posts/:postId` | Dynamic parameter |
-| `posts_.$postId.edit.tsx` | `routes/posts_.$postId.edit.tsx` | `/posts/:postId/edit` | Pathless parent layout |
-| `_auth.tsx` | `routes/_auth.tsx` | - | Pathless layout (no URL segment) |
-| `_auth.login.tsx` | `routes/_auth.login.tsx` | `/login` | Child of pathless layout |
-| `(marketing)/` | `routes/(marketing)/about.tsx` | `/about` | Route group (organization only) |
-| `$.tsx` | `routes/$.tsx` | `/*` | Catch-all/splat route |
-
-## Route File Structure
-
-### Basic Route
-```typescript
-// routes/about.tsx
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/about')({
-  component: AboutPage,
-})
-
-function AboutPage() {
-  return <div>About Page</div>
-}
-```
-
-### Route with Loader
-```typescript
-// routes/posts.$postId.tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { postQueryOptions } from '@/features/posts/queries'
-
-export const Route = createFileRoute('/posts/$postId')({
-  loader: ({ context: { queryClient }, params }) =>
-    queryClient.ensureQueryData(postQueryOptions(params.postId)),
-  component: PostDetailPage,
-})
-
-function PostDetailPage() {
-  const { postId } = Route.useParams()
-  const post = Route.useLoaderData()
-
-  return <PostDetail post={post} />
-}
-```
-
-### Route with Search Params
-```typescript
-// routes/posts.tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { z } from 'zod'
-
-const postsSearchSchema = z.object({
-  page: z.number().default(1),
-  sort: z.enum(['newest', 'oldest', 'popular']).default('newest'),
-  search: z.string().optional(),
-})
-
-export const Route = createFileRoute('/posts')({
-  validateSearch: postsSearchSchema,
-  component: PostsPage,
-})
-
-function PostsPage() {
-  const { page, sort, search } = Route.useSearch()
-  const navigate = Route.useNavigate()
-
-  const setPage = (newPage: number) => {
-    navigate({ search: (prev) => ({ ...prev, page: newPage }) })
-  }
-
-  return <PostList page={page} sort={sort} search={search} onPageChange={setPage} />
-}
-```
-
-### Root Route with Context
-```typescript
-// routes/__root.tsx
-import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
-import type { QueryClient } from '@tanstack/react-query'
-
-interface RouterContext {
-  queryClient: QueryClient
-}
-
-export const Route = createRootRouteWithContext<RouterContext>()({
-  component: RootComponent,
-  beforeLoad: async ({ context }) => {
-    // Auth check, theme loading, etc.
-    return { user: await getUser() }
-  },
-})
-
-function RootComponent() {
-  return (
-    <div>
-      <Header />
-      <Outlet />
-      <Footer />
-    </div>
-  )
-}
-```
-
-### Pathless Layout Route
-```typescript
-// routes/_auth.tsx
-import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/_auth')({
-  beforeLoad: async ({ context }) => {
-    if (!context.user) {
-      throw redirect({ to: '/login' })
-    }
-  },
-  component: AuthLayout,
-})
-
-function AuthLayout() {
-  return (
-    <div className="authenticated-layout">
-      <Sidebar />
-      <main>
-        <Outlet />
-      </main>
-    </div>
-  )
-}
-```
-
-## Navigation Patterns
-
-### Declarative Navigation
-```typescript
-import { Link } from '@tanstack/react-router'
-
-// Basic link
-<Link to="/about">About</Link>
-
-// With params
-<Link to="/posts/$postId" params={{ postId: '123' }}>
-  View Post
-</Link>
-
-// With search params
-<Link to="/posts" search={{ page: 2, sort: 'newest' }}>
-  Page 2
-</Link>
-
-// Active styling
-<Link
-  to="/posts"
-  activeProps={{ className: 'active' }}
-  inactiveProps={{ className: 'inactive' }}
->
-  Posts
-</Link>
-```
-
-### Imperative Navigation
-```typescript
-import { useNavigate } from '@tanstack/react-router'
-
-function PostCard({ post }) {
-  const navigate = useNavigate()
-
-  const handleClick = () => {
-    navigate({
-      to: '/posts/$postId',
-      params: { postId: post.id },
-      search: { tab: 'comments' }
-    })
-  }
-
-  return <div onClick={handleClick}>{post.title}</div>
-}
-```
-
-### Programmatic Redirect
-```typescript
-import { redirect } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/admin')({
-  beforeLoad: async ({ context }) => {
-    if (!context.user?.isAdmin) {
-      throw redirect({ to: '/', search: { error: 'unauthorized' } })
-    }
-  },
-})
-```
-
-## Error Handling
-
-### Route Error Boundary
-```typescript
-export const Route = createFileRoute('/posts/$postId')({
-  loader: async ({ params }) => {
-    const post = await getPost(params.postId)
-    if (!post) {
-      throw new Error('Post not found')
-    }
-    return post
-  },
-  errorComponent: ({ error }) => (
-    <div className="error">
-      <h2>Error loading post</h2>
-      <p>{error.message}</p>
-    </div>
-  ),
-  component: PostPage,
-})
-```
-
-### Pending Component
-```typescript
-export const Route = createFileRoute('/posts')({
-  pendingComponent: () => <div>Loading posts...</div>,
-  pendingMinMs: 500, // Show pending after 500ms
-  pendingMs: 1000,   // Minimum pending display time
-  component: PostsPage,
-})
-```
-
-## Conventions to Enforce
-
-1. **Always use `createFileRoute`** - Never manual route configuration
-2. **Type-safe params** - Use `Route.useParams()` for full type inference
-3. **Validate search params** - Use Zod schemas with `validateSearch`
-4. **Loaders for data** - Prefetch with `ensureQueryData`, not direct fetches
-5. **Context for shared data** - Auth, theme, queryClient in root context
-6. **Error boundaries** - Always provide `errorComponent` for data routes
-7. **Pathless layouts** - Use `_` prefix for auth guards, feature layouts
-
-## Anti-Patterns to Block
-
-```typescript
-// ❌ WRONG: Manual route definition
-const router = createRouter({
-  routes: [{ path: '/posts', component: Posts }]
-})
-
-// ✅ CORRECT: File-based routes
-// routes/posts.tsx with createFileRoute
-
-// ❌ WRONG: useParams from react-router-dom
-import { useParams } from 'react-router-dom'
-
-// ✅ CORRECT: Route-specific useParams
-const { postId } = Route.useParams()
-
-// ❌ WRONG: Unvalidated search params
-const search = new URLSearchParams(window.location.search)
-
-// ✅ CORRECT: Validated with Zod
-const { page, sort } = Route.useSearch()
-
-// ❌ WRONG: Direct fetch in loader
-loader: async () => {
-  const response = await fetch('/api/posts')
-  return response.json()
-}
-
-// ✅ CORRECT: Use query client
-loader: ({ context: { queryClient } }) =>
-  queryClient.ensureQueryData(postsQueryOptions())
-```

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

@@ -1,351 +0,0 @@
----
-name: TanStack Store Patterns (Alpha)
-description: >-
-  TanStack Store patterns for framework-agnostic reactive state. Activates when
-  implementing client-side state, global stores, or reactive state management
-  in React applications. NOTE: Alpha library - API may change.
-version: 1.0.0
----
-
-# TanStack Store Patterns (Alpha)
-
-> **Alpha Library**: TanStack Store is in alpha. APIs may change between versions.
-
-This skill covers TanStack Store for framework-agnostic reactive state management.
-
-## Basic Store
-
-```typescript
-// lib/stores/counter-store.ts
-import { Store } from '@tanstack/store'
-
-export const counterStore = new Store({
-  count: 0,
-})
-
-// Actions
-export const increment = () => {
-  counterStore.setState((state) => ({
-    ...state,
-    count: state.count + 1,
-  }))
-}
-
-export const decrement = () => {
-  counterStore.setState((state) => ({
-    ...state,
-    count: state.count - 1,
-  }))
-}
-
-export const reset = () => {
-  counterStore.setState((state) => ({
-    ...state,
-    count: 0,
-  }))
-}
-```
-
-## Using Store in React
-
-```typescript
-import { useStore } from '@tanstack/react-store'
-import { counterStore, increment, decrement, reset } from '@/lib/stores/counter-store'
-
-function Counter() {
-  const count = useStore(counterStore, (state) => state.count)
-
-  return (
-    <div>
-      <span>Count: {count}</span>
-      <button onClick={decrement}>-</button>
-      <button onClick={increment}>+</button>
-      <button onClick={reset}>Reset</button>
-    </div>
-  )
-}
-```
-
-## Complex Store with Derived State
-
-```typescript
-// lib/stores/cart-store.ts
-import { Store } from '@tanstack/store'
-
-interface CartItem {
-  id: string
-  name: string
-  price: number
-  quantity: number
-}
-
-interface CartState {
-  items: CartItem[]
-}
-
-export const cartStore = new Store<CartState>({
-  items: [],
-})
-
-// Derived selectors
-export const selectCartItems = (state: CartState) => state.items
-
-export const selectCartTotal = (state: CartState) =>
-  state.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
-
-export const selectCartCount = (state: CartState) =>
-  state.items.reduce((sum, item) => sum + item.quantity, 0)
-
-// Actions
-export const addToCart = (item: Omit<CartItem, 'quantity'>) => {
-  cartStore.setState((state) => {
-    const existing = state.items.find((i) => i.id === item.id)
-    if (existing) {
-      return {
-        ...state,
-        items: state.items.map((i) =>
-          i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i
-        ),
-      }
-    }
-    return {
-      ...state,
-      items: [...state.items, { ...item, quantity: 1 }],
-    }
-  })
-}
-
-export const removeFromCart = (itemId: string) => {
-  cartStore.setState((state) => ({
-    ...state,
-    items: state.items.filter((i) => i.id !== itemId),
-  }))
-}
-
-export const updateQuantity = (itemId: string, quantity: number) => {
-  if (quantity <= 0) {
-    removeFromCart(itemId)
-    return
-  }
-  cartStore.setState((state) => ({
-    ...state,
-    items: state.items.map((i) =>
-      i.id === itemId ? { ...i, quantity } : i
-    ),
-  }))
-}
-
-export const clearCart = () => {
-  cartStore.setState(() => ({ items: [] }))
-}
-```
-
-## Using Complex Store
-
-```typescript
-import { useStore } from '@tanstack/react-store'
-import {
-  cartStore,
-  selectCartItems,
-  selectCartTotal,
-  selectCartCount,
-  updateQuantity,
-  removeFromCart,
-} from '@/lib/stores/cart-store'
-
-function CartSummary() {
-  const count = useStore(cartStore, selectCartCount)
-  const total = useStore(cartStore, selectCartTotal)
-
-  return (
-    <div>
-      <span>{count} items</span>
-      <span>${total.toFixed(2)}</span>
-    </div>
-  )
-}
-
-function CartItems() {
-  const items = useStore(cartStore, selectCartItems)
-
-  return (
-    <ul>
-      {items.map((item) => (
-        <li key={item.id}>
-          <span>{item.name}</span>
-          <input
-            type="number"
-            value={item.quantity}
-            onChange={(e) => updateQuantity(item.id, parseInt(e.target.value))}
-            min={0}
-          />
-          <button onClick={() => removeFromCart(item.id)}>Remove</button>
-        </li>
-      ))}
-    </ul>
-  )
-}
-```
-
-## Store with Persistence
-
-```typescript
-// lib/stores/theme-store.ts
-import { Store } from '@tanstack/store'
-
-type Theme = 'light' | 'dark' | 'system'
-
-interface ThemeState {
-  theme: Theme
-}
-
-const getInitialTheme = (): Theme => {
-  if (typeof window === 'undefined') return 'system'
-  const stored = localStorage.getItem('theme')
-  if (stored === 'light' || stored === 'dark' || stored === 'system') {
-    return stored
-  }
-  return 'system'
-}
-
-export const themeStore = new Store<ThemeState>({
-  theme: getInitialTheme(),
-})
-
-// Subscribe to persist changes
-themeStore.subscribe(() => {
-  const { theme } = themeStore.state
-  localStorage.setItem('theme', theme)
-
-  // Apply theme to document
-  const root = document.documentElement
-  if (theme === 'system') {
-    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
-    root.classList.toggle('dark', prefersDark)
-  } else {
-    root.classList.toggle('dark', theme === 'dark')
-  }
-})
-
-export const setTheme = (theme: Theme) => {
-  themeStore.setState(() => ({ theme }))
-}
-```
-
-## Store Factory Pattern
-
-```typescript
-// lib/stores/create-entity-store.ts
-import { Store } from '@tanstack/store'
-
-interface EntityState<T> {
-  entities: Record<string, T>
-  ids: string[]
-  loading: boolean
-  error: string | null
-}
-
-export function createEntityStore<T extends { id: string }>() {
-  const store = new Store<EntityState<T>>({
-    entities: {},
-    ids: [],
-    loading: false,
-    error: null,
-  })
-
-  return {
-    store,
-
-    selectAll: (state: EntityState<T>) =>
-      state.ids.map((id) => state.entities[id]),
-
-    selectById: (id: string) => (state: EntityState<T>) =>
-      state.entities[id],
-
-    setMany: (items: T[]) => {
-      store.setState((state) => ({
-        ...state,
-        entities: items.reduce((acc, item) => ({ ...acc, [item.id]: item }), state.entities),
-        ids: [...new Set([...state.ids, ...items.map((i) => i.id)])],
-      }))
-    },
-
-    setOne: (item: T) => {
-      store.setState((state) => ({
-        ...state,
-        entities: { ...state.entities, [item.id]: item },
-        ids: state.ids.includes(item.id) ? state.ids : [...state.ids, item.id],
-      }))
-    },
-
-    removeOne: (id: string) => {
-      store.setState((state) => {
-        const { [id]: removed, ...entities } = state.entities
-        return {
-          ...state,
-          entities,
-          ids: state.ids.filter((i) => i !== id),
-        }
-      })
-    },
-
-    setLoading: (loading: boolean) => {
-      store.setState((state) => ({ ...state, loading }))
-    },
-
-    setError: (error: string | null) => {
-      store.setState((state) => ({ ...state, error }))
-    },
-  }
-}
-
-// Usage
-const usersStore = createEntityStore<User>()
-```
-
-## When to Use TanStack Store vs Query
-
-| Use Case | Solution |
-|----------|----------|
-| Server data | TanStack Query |
-| URL state | TanStack Router |
-| Form state | TanStack Form |
-| Local UI state | React useState |
-| Shared client state | TanStack Store |
-| Theme/preferences | TanStack Store + localStorage |
-| Cart/wishlist | TanStack Store |
-
-## Conventions
-
-1. **Separate stores by domain** - One store per feature/concern
-2. **Selector functions** - Define selectors for derived state
-3. **Action functions** - Export actions, don't expose setState directly
-4. **Type safety** - Always type your store state
-5. **Persistence** - Use subscribe for localStorage sync
-6. **Prefer Query** - Use Query for server state, Store for client-only
-
-## Anti-Patterns
-
-```typescript
-// ❌ WRONG: Mutating state directly
-cartStore.state.items.push(newItem)
-
-// ✅ CORRECT: Using setState
-cartStore.setState((state) => ({
-  ...state,
-  items: [...state.items, newItem],
-}))
-
-// ❌ WRONG: Storing server data
-const postsStore = new Store({ posts: [] })
-
-// ✅ CORRECT: Use Query for server data
-const { data: posts } = useQuery(postsQueryOptions())
-
-// ❌ WRONG: Exposing setState directly
-export { counterStore }
-// Component: counterStore.setState(...)
-
-// ✅ CORRECT: Export action functions
-export const increment = () => counterStore.setState(...)
-```