@smicolon/ai-kit 0.0.1 → 0.1.1

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

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

@@ -0,0 +1,346 @@
+---
+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())
+```