@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/hono/skills/cloudflare-bindings/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: cloudflare-bindings
+description: This skill activates when working with Cloudflare Workers bindings like D1, KV, R2, Durable Objects, or environment variables. It provides patterns for database access, caching, file storage, and secrets management.
+---
+
+# Cloudflare Bindings
+
+Patterns for Cloudflare Workers bindings in Hono.
+
+## Type Definitions
+
+Define all bindings in a central type:
+
+```typescript
+// types/bindings.ts
+export type Env = {
+  Bindings: {
+    // D1 Database
+    DB: D1Database
+
+    // KV Namespace
+    KV: KVNamespace
+
+    // R2 Bucket
+    BUCKET: R2Bucket
+
+    // Durable Object
+    COUNTER: DurableObjectNamespace
+
+    // Environment Variables
+    ENVIRONMENT: 'development' | 'staging' | 'production'
+    API_KEY: string
+    JWT_SECRET: string
+  }
+  Variables: {
+    user: User
+    requestId: string
+  }
+}
+```
+
+## D1 Database
+
+### Basic Queries
+
+```typescript
+app.get('/users', async (c) => {
+  const db = c.env.DB
+
+  // Select all
+  const { results } = await db
+    .prepare('SELECT * FROM users WHERE deleted_at IS NULL')
+    .all()
+
+  return c.json({ data: results })
+})
+
+app.get('/users/:id', async (c) => {
+  const db = c.env.DB
+  const id = c.req.param('id')
+
+  // Select one
+  const user = await db
+    .prepare('SELECT * FROM users WHERE id = ?')
+    .bind(id)
+    .first()
+
+  if (!user) {
+    return c.json({ error: 'User not found' }, 404)
+  }
+
+  return c.json({ data: user })
+})
+```
+
+### Insert and Update
+
+```typescript
+app.post('/users', async (c) => {
+  const db = c.env.DB
+  const { email, name } = c.req.valid('json')
+  const id = crypto.randomUUID()
+
+  const result = await db
+    .prepare('INSERT INTO users (id, email, name) VALUES (?, ?, ?)')
+    .bind(id, email, name)
+    .run()
+
+  return c.json({ data: { id, email, name } }, 201)
+})
+
+app.put('/users/:id', async (c) => {
+  const db = c.env.DB
+  const id = c.req.param('id')
+  const { name } = c.req.valid('json')
+
+  await db
+    .prepare('UPDATE users SET name = ?, updated_at = datetime("now") WHERE id = ?')
+    .bind(name, id)
+    .run()
+
+  return c.json({ data: { id, name } })
+})
+```
+
+### Transactions (Batch)
+
+```typescript
+app.post('/transfer', async (c) => {
+  const db = c.env.DB
+  const { fromId, toId, amount } = c.req.valid('json')
+
+  // D1 batch for transaction-like behavior
+  const results = await db.batch([
+    db.prepare('UPDATE accounts SET balance = balance - ? WHERE id = ?')
+      .bind(amount, fromId),
+    db.prepare('UPDATE accounts SET balance = balance + ? WHERE id = ?')
+      .bind(amount, toId),
+    db.prepare('INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)')
+      .bind(fromId, toId, amount)
+  ])
+
+  return c.json({ success: true })
+})
+```
+
+### Pagination
+
+```typescript
+app.get('/users', async (c) => {
+  const db = c.env.DB
+  const { page, limit } = c.req.valid('query')
+  const offset = (page - 1) * limit
+
+  const [users, countResult] = await Promise.all([
+    db.prepare('SELECT * FROM users LIMIT ? OFFSET ?')
+      .bind(limit, offset)
+      .all(),
+    db.prepare('SELECT COUNT(*) as total FROM users')
+      .first<{ total: number }>()
+  ])
+
+  return c.json({
+    data: users.results,
+    meta: {
+      page,
+      limit,
+      total: countResult?.total || 0
+    }
+  })
+})
+```
+
+## KV Namespace
+
+### Basic Operations
+
+```typescript
+// Get
+app.get('/cache/:key', async (c) => {
+  const kv = c.env.KV
+  const key = c.req.param('key')
+
+  const value = await kv.get(key)
+
+  if (!value) {
+    return c.json({ error: 'Not found' }, 404)
+  }
+
+  return c.json({ data: value })
+})
+
+// Get as JSON
+const data = await kv.get('config', 'json')
+
+// Get with metadata
+const { value, metadata } = await kv.getWithMetadata('key')
+
+// Put
+await kv.put('key', 'value')
+
+// Put with TTL (seconds)
+await kv.put('session', token, { expirationTtl: 3600 })
+
+// Put with expiration (Unix timestamp)
+await kv.put('temp', data, { expiration: Date.now() / 1000 + 3600 })
+
+// Put with metadata
+await kv.put('user:123', JSON.stringify(user), {
+  metadata: { createdAt: Date.now() }
+})
+
+// Delete
+await kv.delete('key')
+
+// List keys
+const { keys } = await kv.list({ prefix: 'user:' })
+```
+
+### Caching Pattern
+
+```typescript
+app.get('/expensive-data', async (c) => {
+  const kv = c.env.KV
+  const cacheKey = 'expensive-data'
+
+  // Try cache first
+  const cached = await kv.get(cacheKey, 'json')
+  if (cached) {
+    return c.json({ data: cached, cached: true })
+  }
+
+  // Compute expensive data
+  const data = await computeExpensiveData()
+
+  // Cache for 5 minutes
+  await kv.put(cacheKey, JSON.stringify(data), { expirationTtl: 300 })
+
+  return c.json({ data, cached: false })
+})
+```
+
+### Rate Limiting
+
+```typescript
+const rateLimiter = createMiddleware<Env>(async (c, next) => {
+  const kv = c.env.KV
+  const ip = c.req.header('CF-Connecting-IP') || 'unknown'
+  const key = `ratelimit:${ip}`
+
+  const count = parseInt(await kv.get(key) || '0')
+
+  if (count >= 100) {
+    return c.json({ error: 'Rate limit exceeded' }, 429)
+  }
+
+  await kv.put(key, String(count + 1), { expirationTtl: 60 })
+
+  await next()
+})
+```
+
+## R2 Bucket
+
+### Upload Files
+
+```typescript
+app.post('/upload', async (c) => {
+  const bucket = c.env.BUCKET
+  const body = await c.req.parseBody()
+  const file = body['file'] as File
+
+  if (!file) {
+    return c.json({ error: 'No file provided' }, 400)
+  }
+
+  const key = `uploads/${crypto.randomUUID()}-${file.name}`
+
+  await bucket.put(key, file.stream(), {
+    httpMetadata: {
+      contentType: file.type
+    },
+    customMetadata: {
+      originalName: file.name,
+      uploadedAt: new Date().toISOString()
+    }
+  })
+
+  return c.json({ key }, 201)
+})
+```
+
+### Download Files
+
+```typescript
+app.get('/files/:key', async (c) => {
+  const bucket = c.env.BUCKET
+  const key = c.req.param('key')
+
+  const object = await bucket.get(key)
+
+  if (!object) {
+    return c.json({ error: 'File not found' }, 404)
+  }
+
+  const headers = new Headers()
+  headers.set('Content-Type', object.httpMetadata?.contentType || 'application/octet-stream')
+  headers.set('Content-Length', String(object.size))
+
+  return new Response(object.body, { headers })
+})
+```
+
+### List Files
+
+```typescript
+app.get('/files', async (c) => {
+  const bucket = c.env.BUCKET
+  const prefix = c.req.query('prefix') || ''
+
+  const listed = await bucket.list({
+    prefix,
+    limit: 100
+  })
+
+  return c.json({
+    data: listed.objects.map(obj => ({
+      key: obj.key,
+      size: obj.size,
+      uploaded: obj.uploaded
+    }))
+  })
+})
+```
+
+### Delete Files
+
+```typescript
+app.delete('/files/:key', async (c) => {
+  const bucket = c.env.BUCKET
+  const key = c.req.param('key')
+
+  await bucket.delete(key)
+
+  return c.body(null, 204)
+})
+```
+
+## Environment Variables
+
+### Access in Handlers
+
+```typescript
+app.get('/config', (c) => {
+  const env = c.env.ENVIRONMENT
+
+  return c.json({
+    environment: env,
+    features: {
+      debug: env === 'development'
+    }
+  })
+})
+```
+
+### Secrets in Middleware
+
+```typescript
+const authMiddleware = createMiddleware<Env>(async (c, next) => {
+  const token = c.req.header('Authorization')?.replace('Bearer ', '')
+
+  if (!token) {
+    throw new HTTPException(401, { message: 'Missing token' })
+  }
+
+  // Use secret from environment
+  const payload = await verify(token, c.env.JWT_SECRET)
+  c.set('user', payload)
+
+  await next()
+})
+```
+
+## wrangler.toml Configuration
+
+```toml
+name = "my-app"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+ENVIRONMENT = "production"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "my-app-db"
+database_id = "xxxx-xxxx-xxxx"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "xxxx-xxxx-xxxx"
+
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "my-app-bucket"
+
+# Secrets are set via wrangler secret put
+# wrangler secret put JWT_SECRET
+```
+
+## Local Development
+
+**.dev.vars** (for local secrets):
+```
+JWT_SECRET=dev-secret-key
+API_KEY=dev-api-key
+```
+
+```bash
+# Run with local D1
+wrangler d1 create my-app-db --local
+
+# Run with local KV
+wrangler kv:namespace create KV --local
+
+# Start dev server
+wrangler dev
+```

package/packs/hono/skills/hono-patterns/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: hono-patterns
+description: This skill activates when writing Hono routes, handlers, middleware, or discussing Hono application architecture. It provides patterns for routing, middleware composition, error handling, and TypeScript integration.
+---
+
+# Hono Patterns
+
+Core patterns for building Hono applications.
+
+## Routing Patterns
+
+### Modular Route Organization
+
+Organize routes in separate files and compose with `app.route()`:
+
+```typescript
+// routes/users.ts
+import { Hono } from 'hono'
+import type { Env } from '../types/bindings'
+
+const users = new Hono<Env>()
+
+users.get('/', (c) => c.json({ users: [] }))
+users.get('/:id', (c) => c.json({ id: c.req.param('id') }))
+users.post('/', (c) => c.json({ created: true }, 201))
+
+export { users }
+
+// index.ts
+import { users } from './routes/users'
+import { posts } from './routes/posts'
+
+app.route('/api/users', users)
+app.route('/api/posts', posts)
+```
+
+### Route Groups with Shared Middleware
+
+```typescript
+const api = new Hono<Env>()
+
+// Apply auth to all /api routes
+api.use('*', authMiddleware)
+
+api.route('/users', users)
+api.route('/posts', posts)
+
+app.route('/api', api)
+
+// Public routes remain unprotected
+app.get('/health', (c) => c.json({ status: 'ok' }))
+```
+
+### Chained Route Definition (for RPC)
+
+```typescript
+// Chain routes for proper type inference
+const routes = app
+  .get('/users', (c) => c.json({ users: [] }))
+  .post('/users', (c) => c.json({ created: true }, 201))
+  .get('/users/:id', (c) => c.json({ id: c.req.param('id') }))
+
+export type AppType = typeof routes
+```
+
+## Handler Patterns
+
+### Basic Handler
+
+```typescript
+app.get('/users', async (c) => {
+  const users = await fetchUsers()
+  return c.json(users)
+})
+```
+
+### Handler with Validation
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+app.post('/users',
+  zValidator('json', z.object({
+    email: z.string().email(),
+    name: z.string().min(1)
+  })),
+  async (c) => {
+    const data = c.req.valid('json')
+    return c.json({ id: crypto.randomUUID(), ...data }, 201)
+  }
+)
+```
+
+### Factory Pattern for External Handlers
+
+Use when handlers need to be defined outside route files:
+
+```typescript
+import { createFactory } from 'hono/factory'
+import type { Env } from '../types/bindings'
+
+const factory = createFactory<Env>()
+
+// Define handler with proper types
+export const listUsers = factory.createHandlers(
+  zValidator('query', paginationSchema),
+  async (c) => {
+    const { page, limit } = c.req.valid('query')
+    return c.json({ users: [], page, limit })
+  }
+)
+
+// Use in routes
+users.get('/', ...listUsers)
+```
+
+## Middleware Patterns
+
+### Creating Typed Middleware
+
+```typescript
+import { createMiddleware } from 'hono/factory'
+import type { Env } from '../types/bindings'
+
+export const loggerMiddleware = createMiddleware<Env>(async (c, next) => {
+  const start = Date.now()
+  await next()
+  console.log(`${c.req.method} ${c.req.url} - ${Date.now() - start}ms`)
+})
+```
+
+### Middleware with Variables
+
+```typescript
+// Update types/bindings.ts
+type Env = {
+  Variables: {
+    user: { id: string; email: string }
+  }
+}
+
+// Middleware sets variable
+const authMiddleware = createMiddleware<Env>(async (c, next) => {
+  const user = await validateToken(c.req.header('Authorization'))
+  c.set('user', user)  // Type-safe!
+  await next()
+})
+
+// Handler accesses variable
+app.get('/profile', authMiddleware, (c) => {
+  const user = c.get('user')  // Type-safe!
+  return c.json(user)
+})
+```
+
+### Configurable Middleware Factory
+
+```typescript
+interface CacheOptions {
+  maxAge: number
+  public?: boolean
+}
+
+export const cache = (options: CacheOptions) => {
+  return createMiddleware<Env>(async (c, next) => {
+    await next()
+
+    const directive = options.public ? 'public' : 'private'
+    c.header('Cache-Control', `${directive}, max-age=${options.maxAge}`)
+  })
+}
+
+// Usage
+app.get('/static/*', cache({ maxAge: 86400, public: true }))
+```
+
+## Error Handling
+
+### HTTPException
+
+```typescript
+import { HTTPException } from 'hono/http-exception'
+
+app.get('/users/:id', async (c) => {
+  const user = await getUser(c.req.param('id'))
+
+  if (!user) {
+    throw new HTTPException(404, { message: 'User not found' })
+  }
+
+  return c.json(user)
+})
+```
+
+### Global Error Handler
+
+```typescript
+app.onError((err, c) => {
+  if (err instanceof HTTPException) {
+    return c.json({ error: err.message }, err.status)
+  }
+
+  console.error(err)
+  return c.json({ error: 'Internal server error' }, 500)
+})
+```
+
+### Custom Error Classes
+
+```typescript
+class NotFoundError extends HTTPException {
+  constructor(resource: string) {
+    super(404, { message: `${resource} not found` })
+  }
+}
+
+class ValidationError extends HTTPException {
+  constructor(errors: Record<string, string>) {
+    super(400, { message: 'Validation failed', cause: errors })
+  }
+}
+```
+
+## Response Patterns
+
+### JSON Responses
+
+```typescript
+// Success
+c.json({ data: users })
+c.json({ data: user }, 200)
+c.json({ data: newUser }, 201)
+
+// Errors
+c.json({ error: 'Not found' }, 404)
+c.json({ error: 'Validation failed', details: errors }, 400)
+
+// No content
+c.body(null, 204)
+```
+
+### Consistent Response Format
+
+```typescript
+interface ApiResponse<T> {
+  data?: T
+  error?: string
+  meta?: {
+    page?: number
+    limit?: number
+    total?: number
+  }
+}
+
+// Helper
+function success<T>(c: Context, data: T, status = 200) {
+  return c.json({ data } as ApiResponse<T>, status)
+}
+
+function error(c: Context, message: string, status = 400) {
+  return c.json({ error: message } as ApiResponse<never>, status)
+}
+```
+
+## Context Access
+
+### Request Data
+
+```typescript
+// Path params
+const id = c.req.param('id')
+const { id, slug } = c.req.param()
+
+// Query params
+const page = c.req.query('page')
+const { page, limit } = c.req.query()
+
+// Headers
+const auth = c.req.header('Authorization')
+
+// Body (validated)
+const data = c.req.valid('json')
+const form = c.req.valid('form')
+const query = c.req.valid('query')
+```
+
+### Environment and Bindings
+
+```typescript
+// Environment variables
+const secret = c.env.JWT_SECRET
+
+// Cloudflare bindings
+const db = c.env.DB
+const kv = c.env.KV
+const bucket = c.env.BUCKET
+```
+
+## Best Practices
+
+1. **Always type your app**: `new Hono<Env>()`
+2. **Validate all inputs** with Zod
+3. **Use `createMiddleware`** for type-safe middleware
+4. **Export `AppType`** for RPC client
+5. **Handle errors** with HTTPException
+6. **Use proper status codes**: 200, 201, 204, 400, 401, 404, 500
+7. **Organize routes** in separate files
+8. **Keep handlers small** - delegate to services