@smicolon/ai-kit 0.3.2 → 0.4.1

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

@@ -1,370 +0,0 @@
----
-name: TanStack AI Patterns (Alpha)
-description: >-
-  TanStack AI patterns for unified AI SDK integration. Activates when
-  implementing AI chat, streaming responses, or AI-powered features.
-  NOTE: Alpha library - API may change.
-version: 1.0.0
----
-
-# TanStack AI Patterns (Alpha)
-
-> **Alpha Library**: TanStack AI is in alpha. APIs may change between versions.
-
-TanStack AI provides a unified SDK for integrating AI capabilities into React applications.
-
-## Core Concepts
-
-- **Providers**: Backend AI providers (OpenAI, Anthropic, etc.)
-- **Streams**: Real-time streaming responses
-- **Chat**: Conversational interfaces
-- **Completion**: Text completion
-- **Hooks**: React hooks for AI interactions
-
-## Basic Setup
-
-```typescript
-// lib/ai.ts
-import { createAI } from '@tanstack/ai'
-
-export const ai = createAI({
-  provider: 'openai',
-  apiKey: import.meta.env.VITE_OPENAI_API_KEY,
-  // Or use server-side proxy
-  baseUrl: '/api/ai',
-})
-```
-
-## Chat Interface
-
-```typescript
-import { useChat } from '@tanstack/ai-react'
-import { ai } from '@/lib/ai'
-
-function ChatInterface() {
-  const {
-    messages,
-    input,
-    setInput,
-    sendMessage,
-    isLoading,
-    error,
-  } = useChat({
-    ai,
-    model: 'gpt-4',
-    systemPrompt: 'You are a helpful assistant.',
-  })
-
-  const handleSubmit = (e: React.FormEvent) => {
-    e.preventDefault()
-    if (input.trim()) {
-      sendMessage(input)
-      setInput('')
-    }
-  }
-
-  return (
-    <div className="chat-container">
-      <div className="messages">
-        {messages.map((message) => (
-          <div
-            key={message.id}
-            className={`message ${message.role}`}
-          >
-            {message.content}
-          </div>
-        ))}
-        {isLoading && <div className="loading">Thinking...</div>}
-      </div>
-
-      <form onSubmit={handleSubmit}>
-        <input
-          value={input}
-          onChange={(e) => setInput(e.target.value)}
-          placeholder="Type a message..."
-          disabled={isLoading}
-        />
-        <button type="submit" disabled={isLoading || !input.trim()}>
-          Send
-        </button>
-      </form>
-
-      {error && <div className="error">{error.message}</div>}
-    </div>
-  )
-}
-```
-
-## Streaming Responses
-
-```typescript
-import { useCompletion } from '@tanstack/ai-react'
-import { ai } from '@/lib/ai'
-
-function StreamingCompletion() {
-  const {
-    completion,
-    complete,
-    isLoading,
-    stop,
-  } = useCompletion({
-    ai,
-    model: 'gpt-4',
-  })
-
-  const handleGenerate = () => {
-    complete('Write a short story about a robot learning to paint.')
-  }
-
-  return (
-    <div>
-      <button onClick={handleGenerate} disabled={isLoading}>
-        Generate Story
-      </button>
-      {isLoading && (
-        <button onClick={stop}>Stop</button>
-      )}
-      <div className="completion">
-        {completion}
-        {isLoading && <span className="cursor">|</span>}
-      </div>
-    </div>
-  )
-}
-```
-
-## Server-Side Proxy Pattern
-
-```typescript
-// For security, proxy AI calls through your server
-
-// api/ai/chat.ts (server route)
-import { OpenAI } from 'openai'
-
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-})
-
-export async function POST(request: Request) {
-  const { messages, model } = await request.json()
-
-  const stream = await openai.chat.completions.create({
-    model,
-    messages,
-    stream: true,
-  })
-
-  return new Response(stream.toReadableStream(), {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    },
-  })
-}
-
-// Client setup
-export const ai = createAI({
-  provider: 'openai',
-  baseUrl: '/api/ai', // Use server proxy
-})
-```
-
-## Chat with Context
-
-```typescript
-import { useChat } from '@tanstack/ai-react'
-
-function ContextualChat({ documentContent }: { documentContent: string }) {
-  const chat = useChat({
-    ai,
-    model: 'gpt-4',
-    systemPrompt: `You are analyzing the following document. Answer questions about it.
-
-Document:
-${documentContent}`,
-  })
-
-  return <ChatUI {...chat} />
-}
-```
-
-## Multi-Turn Conversation
-
-```typescript
-import { useChat } from '@tanstack/ai-react'
-import { useState } from 'react'
-
-function ConversationWithHistory() {
-  const [conversations, setConversations] = useState<Conversation[]>([])
-  const [activeConversation, setActiveConversation] = useState<string | null>(null)
-
-  const chat = useChat({
-    ai,
-    model: 'gpt-4',
-    initialMessages: activeConversation
-      ? conversations.find(c => c.id === activeConversation)?.messages
-      : [],
-    onFinish: (message) => {
-      // Save conversation
-      if (activeConversation) {
-        setConversations(prev =>
-          prev.map(c =>
-            c.id === activeConversation
-              ? { ...c, messages: [...c.messages, message] }
-              : c
-          )
-        )
-      }
-    },
-  })
-
-  const startNewConversation = () => {
-    const id = crypto.randomUUID()
-    setConversations(prev => [...prev, { id, messages: [] }])
-    setActiveConversation(id)
-  }
-
-  return (
-    <div className="flex">
-      <aside>
-        <button onClick={startNewConversation}>New Chat</button>
-        {conversations.map(conv => (
-          <button
-            key={conv.id}
-            onClick={() => setActiveConversation(conv.id)}
-            className={activeConversation === conv.id ? 'active' : ''}
-          >
-            Conversation {conv.id.slice(0, 8)}
-          </button>
-        ))}
-      </aside>
-      <main>
-        <ChatUI {...chat} />
-      </main>
-    </div>
-  )
-}
-```
-
-## Function Calling
-
-```typescript
-import { useChat } from '@tanstack/ai-react'
-
-const functions = [
-  {
-    name: 'get_weather',
-    description: 'Get the current weather for a location',
-    parameters: {
-      type: 'object',
-      properties: {
-        location: { type: 'string', description: 'City name' },
-      },
-      required: ['location'],
-    },
-  },
-]
-
-function ChatWithFunctions() {
-  const chat = useChat({
-    ai,
-    model: 'gpt-4',
-    functions,
-    onFunctionCall: async (name, args) => {
-      if (name === 'get_weather') {
-        const weather = await fetchWeather(args.location)
-        return JSON.stringify(weather)
-      }
-      return null
-    },
-  })
-
-  return <ChatUI {...chat} />
-}
-```
-
-## Integration with Query
-
-```typescript
-import { useQuery } from '@tanstack/react-query'
-import { useChat } from '@tanstack/ai-react'
-
-function AIAssistedSearch({ query }: { query: string }) {
-  // Fetch data with Query
-  const { data: results } = useQuery({
-    queryKey: ['search', query],
-    queryFn: () => searchApi.search(query),
-  })
-
-  // Use AI to summarize results
-  const { completion, complete } = useCompletion({
-    ai,
-    model: 'gpt-4',
-  })
-
-  useEffect(() => {
-    if (results?.length) {
-      complete(`Summarize these search results:\n${JSON.stringify(results)}`)
-    }
-  }, [results])
-
-  return (
-    <div>
-      <h2>AI Summary</h2>
-      <p>{completion}</p>
-      <h2>Results</h2>
-      <ResultsList results={results} />
-    </div>
-  )
-}
-```
-
-## Conventions
-
-1. **Server proxy** - Never expose API keys to client
-2. **Streaming** - Use streaming for better UX
-3. **Error handling** - Always handle AI errors gracefully
-4. **Rate limiting** - Implement client-side throttling
-5. **Token management** - Track and limit token usage
-6. **Cancellation** - Allow users to stop generation
-
-## Anti-Patterns
-
-```typescript
-// ❌ WRONG: API key in client
-const ai = createAI({
-  provider: 'openai',
-  apiKey: 'sk-...', // Never do this!
-})
-
-// ✅ CORRECT: Use server proxy
-const ai = createAI({
-  provider: 'openai',
-  baseUrl: '/api/ai',
-})
-
-// ❌ WRONG: No loading state
-function Chat() {
-  const { messages, sendMessage } = useChat({ ai })
-  return <div>{messages.map(...)}</div>
-}
-
-// ✅ CORRECT: Show loading state
-function Chat() {
-  const { messages, sendMessage, isLoading } = useChat({ ai })
-  return (
-    <div>
-      {messages.map(...)}
-      {isLoading && <Typing />}
-    </div>
-  )
-}
-
-// ❌ WRONG: No error handling
-const { completion } = useCompletion({ ai })
-
-// ✅ CORRECT: Handle errors
-const { completion, error } = useCompletion({ ai })
-if (error) return <ErrorMessage error={error} />
-```

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

@@ -1,346 +0,0 @@
----
-name: TanStack DB Patterns (Beta)
-description: >-
-  TanStack DB patterns for client-first reactive data stores. Activates when
-  implementing offline-first apps, local-first data, or reactive client databases.
-  NOTE: Beta library - API may change.
-version: 1.0.0
----
-
-# TanStack DB Patterns (Beta)
-
-> **Beta Library**: TanStack DB is in beta. APIs may change between versions.
-
-TanStack DB provides a client-first reactive data store with optional sync to remote sources.
-
-## Core Concepts
-
-- **Collections**: Named groups of documents (like tables)
-- **Documents**: Individual records with unique IDs
-- **Queries**: Reactive queries that update when data changes
-- **Transactions**: Atomic operations across multiple documents
-- **Sync**: Optional sync to remote backends
-
-## Basic Setup
-
-```typescript
-// lib/db.ts
-import { createDB, createCollection } from '@tanstack/db'
-
-// Define document types
-interface Post {
-  id: string
-  title: string
-  content: string
-  authorId: string
-  published: boolean
-  createdAt: number
-  updatedAt: number
-}
-
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-// Create database
-export const db = createDB({
-  collections: {
-    posts: createCollection<Post>(),
-    users: createCollection<User>(),
-  },
-})
-```
-
-## CRUD Operations
-
-### Create
-```typescript
-import { db } from '@/lib/db'
-
-// Insert a single document
-const newPost = await db.posts.insert({
-  id: crypto.randomUUID(),
-  title: 'My Post',
-  content: 'Post content...',
-  authorId: 'user-1',
-  published: false,
-  createdAt: Date.now(),
-  updatedAt: Date.now(),
-})
-
-// Insert multiple documents
-await db.posts.insertMany([
-  { id: '1', title: 'Post 1', ... },
-  { id: '2', title: 'Post 2', ... },
-])
-```
-
-### Read
-```typescript
-// Get by ID
-const post = await db.posts.get('post-id')
-
-// Query with filters
-const publishedPosts = await db.posts.findMany({
-  where: { published: true },
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
-})
-
-// Query with complex filters
-const userPosts = await db.posts.findMany({
-  where: {
-    authorId: 'user-1',
-    published: true,
-  },
-})
-```
-
-### Update
-```typescript
-// Update by ID
-await db.posts.update('post-id', {
-  title: 'Updated Title',
-  updatedAt: Date.now(),
-})
-
-// Update with function
-await db.posts.update('post-id', (post) => ({
-  ...post,
-  viewCount: post.viewCount + 1,
-  updatedAt: Date.now(),
-}))
-
-// Update many
-await db.posts.updateMany(
-  { where: { authorId: 'user-1' } },
-  { published: false }
-)
-```
-
-### Delete
-```typescript
-// Delete by ID
-await db.posts.delete('post-id')
-
-// Delete many
-await db.posts.deleteMany({
-  where: { published: false },
-})
-```
-
-## Reactive Queries in React
-
-```typescript
-import { useQuery } from '@tanstack/db-react'
-import { db } from '@/lib/db'
-
-function PostList() {
-  // Reactive query - updates when data changes
-  const posts = useQuery(
-    db.posts.query({
-      where: { published: true },
-      orderBy: { createdAt: 'desc' },
-    })
-  )
-
-  return (
-    <ul>
-      {posts.map((post) => (
-        <PostCard key={post.id} post={post} />
-      ))}
-    </ul>
-  )
-}
-
-function PostDetail({ postId }: { postId: string }) {
-  // Single document query
-  const post = useQuery(db.posts.get(postId))
-
-  if (!post) return <NotFound />
-
-  return <article>{post.title}</article>
-}
-```
-
-## Transactions
-
-```typescript
-import { db } from '@/lib/db'
-
-async function transferPost(postId: string, newAuthorId: string) {
-  await db.transaction(async (tx) => {
-    // Get current post
-    const post = await tx.posts.get(postId)
-    if (!post) throw new Error('Post not found')
-
-    // Update post author
-    await tx.posts.update(postId, {
-      authorId: newAuthorId,
-      updatedAt: Date.now(),
-    })
-
-    // Update user post counts (if tracking)
-    await tx.users.update(post.authorId, (user) => ({
-      ...user,
-      postCount: user.postCount - 1,
-    }))
-
-    await tx.users.update(newAuthorId, (user) => ({
-      ...user,
-      postCount: user.postCount + 1,
-    }))
-  })
-}
-```
-
-## Sync with Remote Backend
-
-```typescript
-// lib/db.ts
-import { createDB, createCollection, createSyncProvider } from '@tanstack/db'
-
-const syncProvider = createSyncProvider({
-  // Pull changes from server
-  pull: async (collection, lastSync) => {
-    const response = await fetch(`/api/${collection}/sync?since=${lastSync}`)
-    return response.json()
-  },
-
-  // Push changes to server
-  push: async (collection, changes) => {
-    await fetch(`/api/${collection}/sync`, {
-      method: 'POST',
-      body: JSON.stringify(changes),
-    })
-  },
-})
-
-export const db = createDB({
-  collections: {
-    posts: createCollection<Post>(),
-    users: createCollection<User>(),
-  },
-  sync: syncProvider,
-})
-
-// Trigger sync
-await db.sync()
-
-// Auto-sync on interval
-setInterval(() => db.sync(), 30000)
-```
-
-## Offline-First Pattern
-
-```typescript
-import { useQuery, useMutation } from '@tanstack/db-react'
-import { db } from '@/lib/db'
-
-function CreatePostForm() {
-  const createPost = useMutation(db.posts.insert)
-
-  const handleSubmit = async (data: PostInput) => {
-    // Immediately available locally
-    await createPost.mutate({
-      id: crypto.randomUUID(),
-      ...data,
-      createdAt: Date.now(),
-      updatedAt: Date.now(),
-      _pending: true, // Mark as pending sync
-    })
-
-    // Sync will happen in background when online
-    if (navigator.onLine) {
-      db.sync()
-    }
-  }
-
-  return <form onSubmit={handleSubmit}>{/* form fields */}</form>
-}
-
-// Show pending items differently
-function PostCard({ post }: { post: Post }) {
-  return (
-    <div className={post._pending ? 'opacity-50' : ''}>
-      {post.title}
-      {post._pending && <span>Syncing...</span>}
-    </div>
-  )
-}
-```
-
-## Integration with TanStack Query
-
-```typescript
-// Hybrid approach: DB for offline, Query for server sync
-import { useQuery as useReactQuery } from '@tanstack/react-query'
-import { useQuery as useDBQuery } from '@tanstack/db-react'
-import { db } from '@/lib/db'
-
-function PostList() {
-  // Local DB for immediate data
-  const localPosts = useDBQuery(
-    db.posts.query({ where: { published: true } })
-  )
-
-  // Server query for sync
-  const { data: serverPosts } = useReactQuery({
-    queryKey: ['posts', 'published'],
-    queryFn: () => postApi.getPosts({ published: true }),
-    onSuccess: (posts) => {
-      // Update local DB with server data
-      db.posts.upsertMany(posts)
-    },
-  })
-
-  // Use local data (always available, even offline)
-  return (
-    <ul>
-      {localPosts.map((post) => (
-        <PostCard key={post.id} post={post} />
-      ))}
-    </ul>
-  )
-}
-```
-
-## When to Use TanStack DB
-
-| Scenario | Solution |
-|----------|----------|
-| Standard server data | TanStack Query |
-| Offline-first app | TanStack DB |
-| Local-first with sync | TanStack DB + sync |
-| Real-time collaboration | TanStack DB + WebSocket sync |
-| Complex client state | TanStack DB or Store |
-
-## Conventions
-
-1. **Type your collections** - Always define document interfaces
-2. **Use transactions** - For multi-document operations
-3. **Handle offline** - Design for offline-first
-4. **Sync strategy** - Define clear sync patterns
-5. **Combine with Query** - Use Query for pure server data
-
-## Anti-Patterns
-
-```typescript
-// ❌ WRONG: Not using transactions for related updates
-await db.posts.delete(postId)
-await db.comments.deleteMany({ where: { postId } }) // Could fail leaving orphans
-
-// ✅ CORRECT: Use transaction
-await db.transaction(async (tx) => {
-  await tx.posts.delete(postId)
-  await tx.comments.deleteMany({ where: { postId } })
-})
-
-// ❌ WRONG: Using DB for pure server data without offline need
-const posts = useDBQuery(db.posts.query({}))
-
-// ✅ CORRECT: Use Query for server data
-const { data: posts } = useQuery(postsQueryOptions())
-```