@smicolon/ai-kit 0.1.0 → 0.2.0

package/packs/hono/skills/rpc-typesafe/SKILL.md

@@ -0,0 +1,388 @@
+---
+name: rpc-typesafe
+description: This skill activates when setting up Hono RPC client, configuring type-safe API calls, or discussing client-server type sharing. It provides patterns for the hc client, type inference, and React Query integration.
+---
+
+# Hono RPC Type Safety
+
+Patterns for type-safe client-server communication with Hono.
+
+## Server Setup
+
+### Export App Type
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+const app = new Hono()
+
+// Define routes with validators for full type inference
+const routes = app
+  .get('/users', async (c) => {
+    return c.json({ users: [{ id: '1', name: 'John' }] })
+  })
+  .post('/users',
+    zValidator('json', z.object({
+      email: z.string().email(),
+      name: z.string()
+    })),
+    async (c) => {
+      const data = c.req.valid('json')
+      return c.json({ id: crypto.randomUUID(), ...data }, 201)
+    }
+  )
+  .get('/users/:id', async (c) => {
+    const id = c.req.param('id')
+    return c.json({ id, name: 'John' })
+  })
+
+export default routes
+
+// CRITICAL: Export type for client
+export type AppType = typeof routes
+```
+
+### Route Chaining for Type Inference
+
+```typescript
+// Chain routes to preserve types
+const userRoutes = new Hono()
+  .get('/', async (c) => c.json({ users: [] }))
+  .post('/',
+    zValidator('json', createUserSchema),
+    async (c) => c.json({ id: '1' }, 201)
+  )
+
+const postRoutes = new Hono()
+  .get('/', async (c) => c.json({ posts: [] }))
+  .post('/',
+    zValidator('json', createPostSchema),
+    async (c) => c.json({ id: '1' }, 201)
+  )
+
+// Compose and export
+const app = new Hono()
+  .route('/users', userRoutes)
+  .route('/posts', postRoutes)
+
+export type AppType = typeof app
+```
+
+## Client Setup
+
+### Basic Client
+
+```typescript
+// client.ts
+import { hc } from 'hono/client'
+import type { AppType } from './server'
+
+// Create typed client
+const client = hc<AppType>('http://localhost:8787')
+
+// Type-safe requests
+const res = await client.users.$get()
+const data = await res.json() // Typed!
+```
+
+### Client Factory
+
+```typescript
+// lib/api-client.ts
+import { hc } from 'hono/client'
+import type { AppType } from '@/server'
+
+export function createClient(baseUrl: string, token?: string) {
+  return hc<AppType>(baseUrl, {
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined
+  })
+}
+
+// Default instance
+export const api = createClient(
+  process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8787'
+)
+```
+
+## Request Patterns
+
+### GET Requests
+
+```typescript
+// Simple GET
+const res = await api.users.$get()
+const { users } = await res.json()
+
+// GET with query params
+const res = await api.users.$get({
+  query: {
+    page: 1,
+    limit: 20,
+    search: 'john'
+  }
+})
+
+// GET with path params
+const res = await api.users[':id'].$get({
+  param: { id: 'user-123' }
+})
+```
+
+### POST Requests
+
+```typescript
+// POST with JSON body
+const res = await api.users.$post({
+  json: {
+    email: 'user@example.com',
+    name: 'New User'
+  }
+})
+
+if (res.ok) {
+  const user = await res.json()
+  console.log(user.id) // Typed!
+}
+```
+
+### PUT/PATCH Requests
+
+```typescript
+const res = await api.users[':id'].$put({
+  param: { id: 'user-123' },
+  json: {
+    name: 'Updated Name'
+  }
+})
+```
+
+### DELETE Requests
+
+```typescript
+const res = await api.users[':id'].$delete({
+  param: { id: 'user-123' }
+})
+
+if (res.status === 204) {
+  console.log('Deleted successfully')
+}
+```
+
+## Type Utilities
+
+### InferRequestType / InferResponseType
+
+```typescript
+import { hc, InferRequestType, InferResponseType } from 'hono/client'
+import type { AppType } from './server'
+
+// Get specific endpoint type
+type CreateUserRequest = InferRequestType<typeof api.users.$post>['json']
+// { email: string; name: string }
+
+type UserResponse = InferResponseType<typeof api.users[':id'].$get>
+// { id: string; name: string }
+
+// Use in functions
+async function createUser(data: CreateUserRequest): Promise<UserResponse> {
+  const res = await api.users.$post({ json: data })
+  return res.json()
+}
+```
+
+### URL Generation
+
+```typescript
+// Generate URL without making request
+const url = api.users[':id'].$url({
+  param: { id: 'user-123' }
+})
+// 'http://localhost:8787/users/user-123'
+
+// Useful for links, prefetching, etc.
+```
+
+## Error Handling
+
+### Response Status Checking
+
+```typescript
+async function getUser(id: string) {
+  const res = await api.users[':id'].$get({ param: { id } })
+
+  if (!res.ok) {
+    if (res.status === 404) {
+      throw new Error('User not found')
+    }
+    throw new Error(`API error: ${res.status}`)
+  }
+
+  return res.json()
+}
+```
+
+### Typed Error Responses
+
+```typescript
+// Server defines error format
+app.get('/users/:id', async (c) => {
+  const user = await getUser(c.req.param('id'))
+
+  if (!user) {
+    return c.json({ error: 'User not found' }, 404)
+  }
+
+  return c.json(user)
+})
+
+// Client handles typed errors
+const res = await api.users[':id'].$get({ param: { id } })
+
+if (res.status === 404) {
+  const { error } = await res.json()
+  console.log(error) // 'User not found'
+}
+```
+
+## React Query Integration
+
+### Query Hooks
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { api } from '@/lib/api-client'
+
+// List query
+export function useUsers(page = 1) {
+  return useQuery({
+    queryKey: ['users', page],
+    queryFn: async () => {
+      const res = await api.users.$get({ query: { page } })
+      if (!res.ok) throw new Error('Failed to fetch users')
+      return res.json()
+    }
+  })
+}
+
+// Single item query
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: ['users', id],
+    queryFn: async () => {
+      const res = await api.users[':id'].$get({ param: { id } })
+      if (!res.ok) throw new Error('User not found')
+      return res.json()
+    },
+    enabled: !!id
+  })
+}
+```
+
+### Mutation Hooks
+
+```typescript
+export function useCreateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async (data: { email: string; name: string }) => {
+      const res = await api.users.$post({ json: data })
+      if (!res.ok) throw new Error('Failed to create user')
+      return res.json()
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    }
+  })
+}
+
+export function useUpdateUser() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: async ({ id, data }: { id: string; data: { name: string } }) => {
+      const res = await api.users[':id'].$put({ param: { id }, json: data })
+      if (!res.ok) throw new Error('Failed to update user')
+      return res.json()
+    },
+    onSuccess: (_, { id }) => {
+      queryClient.invalidateQueries({ queryKey: ['users', id] })
+    }
+  })
+}
+```
+
+### Component Usage
+
+```typescript
+function UserList() {
+  const { data, isLoading, error } = useUsers()
+  const createUser = useCreateUser()
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <div>
+      {data?.users.map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+
+      <button
+        onClick={() => createUser.mutate({
+          email: 'new@example.com',
+          name: 'New User'
+        })}
+      >
+        Add User
+      </button>
+    </div>
+  )
+}
+```
+
+## Configuration Requirements
+
+### TypeScript Config
+
+Both server and client need strict mode:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### Status Codes for Type Discrimination
+
+```typescript
+// Server: Explicit status codes enable type inference
+app.post('/users', async (c) => {
+  return c.json({ id: '1', name: 'User' }, 201) // 201 for created
+})
+
+app.get('/users/:id', async (c) => {
+  const user = await getUser(id)
+  if (!user) {
+    return c.json({ error: 'Not found' }, 404) // 404 for not found
+  }
+  return c.json(user, 200) // 200 for success
+})
+```
+
+## Best Practices
+
+1. **Always export `AppType`** from server
+2. **Chain routes** for proper type inference
+3. **Use `zValidator`** for automatic request type inference
+4. **Specify status codes** for response type discrimination
+5. **Use `strict: true`** in both server and client tsconfig
+6. **Create typed error handlers** for consistent error responses
+7. **Wrap in React Query** for caching and state management
+8. **Use `InferRequestType`/`InferResponseType`** for complex types

package/packs/hono/skills/zod-validation/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: zod-validation
+description: This skill activates when writing form validation, request validation, or Zod schemas in Hono. It provides patterns for validating JSON bodies, query parameters, path parameters, and headers with proper error handling.
+---
+
+# Zod Validation in Hono
+
+Patterns for request validation using Zod and @hono/zod-validator.
+
+## Setup
+
+```bash
+bun add zod @hono/zod-validator
+```
+
+## Basic Validation
+
+### JSON Body
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  name: z.string().min(1, 'Name is required').max(100),
+  age: z.number().int().positive().optional(),
+})
+
+app.post('/users',
+  zValidator('json', createUserSchema),
+  async (c) => {
+    const data = c.req.valid('json')
+    // data is typed as { email: string; name: string; age?: number }
+    return c.json(data, 201)
+  }
+)
+```
+
+### Query Parameters
+
+```typescript
+const paginationSchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  sort: z.enum(['asc', 'desc']).default('desc'),
+  search: z.string().optional(),
+})
+
+app.get('/users',
+  zValidator('query', paginationSchema),
+  async (c) => {
+    const { page, limit, sort, search } = c.req.valid('query')
+    // All values are properly typed and coerced
+    return c.json({ page, limit, sort, search })
+  }
+)
+```
+
+### Path Parameters
+
+```typescript
+const userParamsSchema = z.object({
+  id: z.string().uuid('Invalid user ID format'),
+})
+
+app.get('/users/:id',
+  zValidator('param', userParamsSchema),
+  async (c) => {
+    const { id } = c.req.valid('param')
+    return c.json({ id })
+  }
+)
+```
+
+### Headers
+
+```typescript
+const authHeaderSchema = z.object({
+  authorization: z.string().startsWith('Bearer '),
+  'x-request-id': z.string().uuid().optional(),
+})
+
+app.get('/protected',
+  zValidator('header', authHeaderSchema),
+  async (c) => {
+    const headers = c.req.valid('header')
+    return c.json({ authenticated: true })
+  }
+)
+```
+
+### Form Data
+
+```typescript
+const uploadSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().optional(),
+  // File validation happens separately
+})
+
+app.post('/upload',
+  zValidator('form', uploadSchema),
+  async (c) => {
+    const { title, description } = c.req.valid('form')
+    return c.json({ title, description })
+  }
+)
+```
+
+## Schema Patterns
+
+### Reusable Field Schemas
+
+```typescript
+// validators/common.ts
+export const emailSchema = z.string().email('Invalid email')
+export const uuidSchema = z.string().uuid('Invalid ID format')
+export const dateSchema = z.coerce.date()
+
+export const paginationSchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+})
+```
+
+### Create/Update Pattern
+
+```typescript
+// validators/user.schema.ts
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  password: z.string().min(8),
+  role: z.enum(['user', 'admin']).default('user'),
+})
+
+// Partial for updates (all fields optional)
+export const updateUserSchema = createUserSchema.partial()
+
+// Omit for specific updates
+export const updatePasswordSchema = createUserSchema.pick({
+  password: true,
+}).extend({
+  currentPassword: z.string(),
+  confirmPassword: z.string(),
+}).refine(data => data.password === data.confirmPassword, {
+  message: 'Passwords do not match',
+  path: ['confirmPassword'],
+})
+
+// Infer TypeScript types
+export type CreateUser = z.infer<typeof createUserSchema>
+export type UpdateUser = z.infer<typeof updateUserSchema>
+```
+
+### Nested Objects
+
+```typescript
+const addressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+  country: z.string(),
+  zip: z.string(),
+})
+
+const orderSchema = z.object({
+  items: z.array(z.object({
+    productId: z.string().uuid(),
+    quantity: z.number().int().positive(),
+  })).min(1, 'At least one item required'),
+  shippingAddress: addressSchema,
+  billingAddress: addressSchema.optional(),
+})
+```
+
+### Conditional Validation
+
+```typescript
+const paymentSchema = z.discriminatedUnion('method', [
+  z.object({
+    method: z.literal('card'),
+    cardNumber: z.string().length(16),
+    cvv: z.string().length(3),
+  }),
+  z.object({
+    method: z.literal('paypal'),
+    paypalEmail: z.string().email(),
+  }),
+  z.object({
+    method: z.literal('bank'),
+    accountNumber: z.string(),
+    routingNumber: z.string(),
+  }),
+])
+```
+
+### Custom Refinements
+
+```typescript
+const registrationSchema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine(data => data.password === data.confirmPassword, {
+  message: 'Passwords must match',
+  path: ['confirmPassword'],
+})
+
+const dateRangeSchema = z.object({
+  startDate: z.coerce.date(),
+  endDate: z.coerce.date(),
+}).refine(data => data.endDate > data.startDate, {
+  message: 'End date must be after start date',
+  path: ['endDate'],
+})
+```
+
+### Transform
+
+```typescript
+const userInputSchema = z.object({
+  email: z.string().email().toLowerCase().trim(),
+  name: z.string().trim(),
+  tags: z.string().transform(s => s.split(',').map(t => t.trim())),
+})
+```
+
+## Custom Error Handling
+
+### Custom Error Hook
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+
+const customValidator = <T extends z.ZodType>(
+  target: 'json' | 'query' | 'param' | 'header' | 'form',
+  schema: T
+) => {
+  return zValidator(target, schema, (result, c) => {
+    if (!result.success) {
+      const errors = result.error.issues.map(issue => ({
+        field: issue.path.join('.'),
+        message: issue.message,
+      }))
+
+      return c.json({
+        error: 'Validation failed',
+        details: errors,
+      }, 400)
+    }
+  })
+}
+
+// Usage
+app.post('/users',
+  customValidator('json', createUserSchema),
+  async (c) => {
+    const data = c.req.valid('json')
+    return c.json(data)
+  }
+)
+```
+
+### Validation Error Response Format
+
+```typescript
+// Standard error format
+{
+  "error": "Validation failed",
+  "details": [
+    { "field": "email", "message": "Invalid email address" },
+    { "field": "name", "message": "Name is required" }
+  ]
+}
+```
+
+## Multiple Validators
+
+Chain validators for different request parts:
+
+```typescript
+app.put('/users/:id',
+  zValidator('param', userParamsSchema),
+  zValidator('json', updateUserSchema),
+  async (c) => {
+    const { id } = c.req.valid('param')
+    const data = c.req.valid('json')
+
+    return c.json({ id, ...data })
+  }
+)
+```
+
+## Type Export Pattern
+
+```typescript
+// validators/user.schema.ts
+import { z } from 'zod'
+
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+})
+
+export const updateUserSchema = createUserSchema.partial()
+
+export const userParamsSchema = z.object({
+  id: z.string().uuid(),
+})
+
+export const userQuerySchema = z.object({
+  page: z.coerce.number().default(1),
+  limit: z.coerce.number().default(20),
+})
+
+// Export inferred types
+export type CreateUser = z.infer<typeof createUserSchema>
+export type UpdateUser = z.infer<typeof updateUserSchema>
+export type UserParams = z.infer<typeof userParamsSchema>
+export type UserQuery = z.infer<typeof userQuerySchema>
+```
+
+## Best Practices
+
+1. **Always use `zValidator`** for all request inputs
+2. **Use `z.coerce`** for query params (they're always strings)
+3. **Provide clear error messages** in schema definitions
+4. **Export inferred types** for use elsewhere
+5. **Create reusable field schemas** for common patterns
+6. **Use `.partial()`** for update schemas
+7. **Use `.refine()`** for cross-field validation
+8. **Set sensible defaults** with `.default()`