@smicolon/ai-kit 0.1.0 → 0.1.1

package/packs/hono/agents/hono-tester.md

@@ -0,0 +1,346 @@
+---
+name: hono-tester
+description: Testing specialist for Hono applications using Bun test and Vitest, covering unit tests, integration tests, and API tests.
+model: inherit
+skills:
+  - hono-patterns
+  - zod-validation
+---
+
+# Hono Tester
+
+You are a testing specialist for Hono applications.
+
+## Current Task
+Write comprehensive tests for the specified Hono code.
+
+## Testing Stack
+- **Bun Projects**: `bun:test` (built-in)
+- **CF Workers**: Vitest + `@cloudflare/vitest-pool-workers`
+- **HTTP Testing**: Hono's built-in `app.request()`
+- **Assertions**: Built-in matchers
+
+## Testing Patterns
+
+### Basic Route Testing (Bun)
+
+```typescript
+// tests/users.test.ts
+import { describe, it, expect, beforeEach } from 'bun:test'
+import app from '../src/index'
+
+describe('Users API', () => {
+  describe('GET /api/users', () => {
+    it('returns list of users', async () => {
+      const res = await app.request('/api/users')
+
+      expect(res.status).toBe(200)
+
+      const data = await res.json()
+      expect(data).toHaveProperty('data')
+      expect(Array.isArray(data.data)).toBe(true)
+    })
+
+    it('supports pagination', async () => {
+      const res = await app.request('/api/users?page=2&limit=10')
+
+      expect(res.status).toBe(200)
+
+      const data = await res.json()
+      expect(data.meta.page).toBe(2)
+      expect(data.meta.limit).toBe(10)
+    })
+  })
+
+  describe('POST /api/users', () => {
+    it('creates a new user', async () => {
+      const res = await app.request('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          email: 'test@example.com',
+          name: 'Test User'
+        })
+      })
+
+      expect(res.status).toBe(201)
+
+      const data = await res.json()
+      expect(data.email).toBe('test@example.com')
+      expect(data.name).toBe('Test User')
+      expect(data.id).toBeDefined()
+    })
+
+    it('returns 400 for invalid email', async () => {
+      const res = await app.request('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          email: 'invalid-email',
+          name: 'Test User'
+        })
+      })
+
+      expect(res.status).toBe(400)
+    })
+
+    it('returns 400 for missing required fields', async () => {
+      const res = await app.request('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({})
+      })
+
+      expect(res.status).toBe(400)
+    })
+  })
+
+  describe('GET /api/users/:id', () => {
+    it('returns user by id', async () => {
+      const userId = 'valid-uuid-here'
+      const res = await app.request(`/api/users/${userId}`)
+
+      expect(res.status).toBe(200)
+
+      const data = await res.json()
+      expect(data.id).toBe(userId)
+    })
+
+    it('returns 404 for non-existent user', async () => {
+      const res = await app.request('/api/users/non-existent-id')
+
+      expect(res.status).toBe(404)
+    })
+
+    it('returns 400 for invalid uuid format', async () => {
+      const res = await app.request('/api/users/invalid-uuid')
+
+      expect(res.status).toBe(400)
+    })
+  })
+})
+```
+
+### Testing with Mocked Bindings
+
+```typescript
+// tests/with-bindings.test.ts
+import { describe, it, expect, mock } from 'bun:test'
+import { Hono } from 'hono'
+import type { Env } from '../src/types/bindings'
+import { users } from '../src/routes/users'
+
+describe('Users with D1', () => {
+  const mockDB = {
+    prepare: mock(() => ({
+      bind: mock(() => ({
+        all: mock(() => Promise.resolve({
+          results: [
+            { id: '1', email: 'user1@test.com', name: 'User 1' },
+            { id: '2', email: 'user2@test.com', name: 'User 2' }
+          ]
+        })),
+        first: mock(() => Promise.resolve({
+          id: '1', email: 'user1@test.com', name: 'User 1'
+        })),
+        run: mock(() => Promise.resolve({ meta: { last_row_id: 1 } }))
+      }))
+    }))
+  }
+
+  const app = new Hono<Env>()
+  app.route('/users', users)
+
+  it('lists users from D1', async () => {
+    const res = await app.request('/users', {}, {
+      DB: mockDB as unknown as D1Database
+    })
+
+    expect(res.status).toBe(200)
+
+    const data = await res.json()
+    expect(data.data).toHaveLength(2)
+  })
+})
+```
+
+### Testing Middleware
+
+```typescript
+// tests/middleware.test.ts
+import { describe, it, expect } from 'bun:test'
+import { Hono } from 'hono'
+import { authMiddleware } from '../src/middleware/auth'
+import type { Env } from '../src/types/bindings'
+
+describe('Auth Middleware', () => {
+  const app = new Hono<Env>()
+
+  app.use('/protected/*', authMiddleware)
+  app.get('/protected/resource', (c) => c.json({ message: 'success' }))
+
+  it('returns 401 without token', async () => {
+    const res = await app.request('/protected/resource')
+
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 401 with invalid token', async () => {
+    const res = await app.request('/protected/resource', {
+      headers: { Authorization: 'Bearer invalid-token' }
+    }, {
+      JWT_SECRET: 'test-secret'
+    })
+
+    expect(res.status).toBe(401)
+  })
+
+  it('allows access with valid token', async () => {
+    // Generate valid JWT for test
+    const token = await generateTestToken()
+
+    const res = await app.request('/protected/resource', {
+      headers: { Authorization: `Bearer ${token}` }
+    }, {
+      JWT_SECRET: 'test-secret'
+    })
+
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+### Testing with Vitest (Cloudflare Workers)
+
+```typescript
+// tests/workers.test.ts
+import { describe, it, expect, beforeAll } from 'vitest'
+import { unstable_dev } from 'wrangler'
+import type { UnstableDevWorker } from 'wrangler'
+
+describe('Worker', () => {
+  let worker: UnstableDevWorker
+
+  beforeAll(async () => {
+    worker = await unstable_dev('src/index.ts', {
+      experimental: { disableExperimentalWarning: true }
+    })
+  })
+
+  afterAll(async () => {
+    await worker.stop()
+  })
+
+  it('responds to health check', async () => {
+    const res = await worker.fetch('/health')
+
+    expect(res.status).toBe(200)
+
+    const data = await res.json()
+    expect(data.status).toBe('ok')
+  })
+})
+```
+
+### Testing Zod Schemas
+
+```typescript
+// tests/validators.test.ts
+import { describe, it, expect } from 'bun:test'
+import { createUserSchema, userQuerySchema } from '../src/validators/user.schema'
+
+describe('User Schemas', () => {
+  describe('createUserSchema', () => {
+    it('validates valid user data', () => {
+      const result = createUserSchema.safeParse({
+        email: 'test@example.com',
+        name: 'Test User'
+      })
+
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects invalid email', () => {
+      const result = createUserSchema.safeParse({
+        email: 'not-an-email',
+        name: 'Test User'
+      })
+
+      expect(result.success).toBe(false)
+      expect(result.error?.issues[0].path).toContain('email')
+    })
+
+    it('rejects empty name', () => {
+      const result = createUserSchema.safeParse({
+        email: 'test@example.com',
+        name: ''
+      })
+
+      expect(result.success).toBe(false)
+    })
+
+    it('applies default role', () => {
+      const result = createUserSchema.parse({
+        email: 'test@example.com',
+        name: 'Test User'
+      })
+
+      expect(result.role).toBe('user')
+    })
+  })
+
+  describe('userQuerySchema', () => {
+    it('coerces string numbers', () => {
+      const result = userQuerySchema.parse({
+        page: '2',
+        limit: '50'
+      })
+
+      expect(result.page).toBe(2)
+      expect(result.limit).toBe(50)
+    })
+
+    it('applies defaults', () => {
+      const result = userQuerySchema.parse({})
+
+      expect(result.page).toBe(1)
+      expect(result.limit).toBe(20)
+    })
+  })
+})
+```
+
+## Test Coverage Goals
+
+- **Unit Tests**: 90%+ coverage on validators and utilities
+- **Integration Tests**: All routes tested with happy path + errors
+- **Edge Cases**: Invalid inputs, missing data, auth failures
+
+## Testing Commands
+
+```bash
+# Run all tests (Bun)
+bun test
+
+# Run with coverage
+bun test --coverage
+
+# Run specific test file
+bun test tests/users.test.ts
+
+# Watch mode
+bun test --watch
+```
+
+## Quality Checklist
+
+- [ ] All routes have tests
+- [ ] Happy paths covered
+- [ ] Error cases covered
+- [ ] Validation tested
+- [ ] Middleware tested
+- [ ] Edge cases handled
+- [ ] Mocks properly typed
+- [ ] No flaky tests
+
+Now write tests for the specified code.

package/packs/hono/commands/middleware-create.md

@@ -0,0 +1,223 @@
+---
+name: middleware-create
+description: Create custom Hono middleware with proper typing
+---
+
+# Create Hono Middleware
+
+Create a new custom middleware following Hono best practices.
+
+## Workflow
+
+### Step 1: Gather Requirements
+
+Ask the user:
+1. **Middleware name** (e.g., "auth", "rateLimit", "logger")
+2. **Purpose** - What should this middleware do?
+3. **Configuration options** - Any parameters needed?
+4. **Variables to set** - What data to pass to handlers?
+5. **When to apply** - Which routes need this?
+
+## Middleware Patterns
+
+### Basic Middleware
+
+```typescript
+// middleware/{name}.ts
+import { createMiddleware } from 'hono/factory'
+import type { Env } from '../types/bindings'
+
+export const {name}Middleware = createMiddleware<Env>(async (c, next) => {
+  // Pre-handler logic
+  console.log(`[${c.req.method}] ${c.req.url}`)
+
+  await next()
+
+  // Post-handler logic (runs after handler)
+  console.log(`Response status: ${c.res.status}`)
+})
+```
+
+### Middleware with Variables
+
+```typescript
+// middleware/auth.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+import { verify } from 'hono/jwt'
+import type { Env } from '../types/bindings'
+
+// First, update types/bindings.ts to include the variable:
+// Variables: {
+//   user: { id: string; email: string; role: string }
+// }
+
+export const authMiddleware = createMiddleware<Env>(async (c, next) => {
+  const authHeader = c.req.header('Authorization')
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    throw new HTTPException(401, { message: 'Missing authorization token' })
+  }
+
+  const token = authHeader.slice(7)
+
+  try {
+    const payload = await verify(token, c.env.JWT_SECRET)
+
+    // Set variable for downstream handlers
+    c.set('user', {
+      id: payload.sub as string,
+      email: payload.email as string,
+      role: payload.role as string
+    })
+
+    await next()
+  } catch {
+    throw new HTTPException(401, { message: 'Invalid or expired token' })
+  }
+})
+```
+
+### Configurable Middleware Factory
+
+```typescript
+// middleware/rateLimit.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+import type { Env } from '../types/bindings'
+
+interface RateLimitOptions {
+  windowMs: number  // Time window in milliseconds
+  max: number       // Max requests per window
+  keyGenerator?: (c: Context) => string
+}
+
+export const rateLimit = (options: RateLimitOptions) => {
+  const { windowMs, max, keyGenerator } = options
+
+  return createMiddleware<Env>(async (c, next) => {
+    const key = keyGenerator
+      ? keyGenerator(c)
+      : c.req.header('CF-Connecting-IP') || 'unknown'
+
+    const cacheKey = `ratelimit:${key}`
+    const kv = c.env.KV
+
+    const current = parseInt(await kv.get(cacheKey) || '0')
+
+    if (current >= max) {
+      throw new HTTPException(429, {
+        message: 'Too many requests, please try again later'
+      })
+    }
+
+    await kv.put(cacheKey, String(current + 1), {
+      expirationTtl: Math.ceil(windowMs / 1000)
+    })
+
+    // Add rate limit headers
+    c.header('X-RateLimit-Limit', String(max))
+    c.header('X-RateLimit-Remaining', String(max - current - 1))
+
+    await next()
+  })
+}
+
+// Usage:
+// app.use('/api/*', rateLimit({ windowMs: 60000, max: 100 }))
+```
+
+### Request Validation Middleware
+
+```typescript
+// middleware/validateRequest.ts
+import { createMiddleware } from 'hono/factory'
+import type { Env } from '../types/bindings'
+
+export const requestIdMiddleware = createMiddleware<Env>(async (c, next) => {
+  const requestId = c.req.header('X-Request-ID') || crypto.randomUUID()
+
+  c.set('requestId', requestId)
+  c.header('X-Request-ID', requestId)
+
+  await next()
+})
+```
+
+### Response Timing Middleware
+
+```typescript
+// middleware/timing.ts
+import { createMiddleware } from 'hono/factory'
+import type { Env } from '../types/bindings'
+
+export const timingMiddleware = createMiddleware<Env>(async (c, next) => {
+  const start = Date.now()
+
+  await next()
+
+  const duration = Date.now() - start
+  c.header('X-Response-Time', `${duration}ms`)
+})
+```
+
+### Error Handling Middleware
+
+```typescript
+// middleware/errorHandler.ts
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
+import type { Env } from '../types/bindings'
+
+export const errorHandler = createMiddleware<Env>(async (c, next) => {
+  try {
+    await next()
+  } catch (error) {
+    if (error instanceof HTTPException) {
+      return c.json(
+        { error: error.message, status: error.status },
+        error.status
+      )
+    }
+
+    console.error('Unhandled error:', error)
+    return c.json(
+      { error: 'Internal server error', status: 500 },
+      500
+    )
+  }
+})
+```
+
+## Generated Files
+
+1. `middleware/{name}.ts` - Middleware implementation
+2. Updated `types/bindings.ts` - Add Variables if needed
+3. Updated `middleware/index.ts` - Barrel export
+
+## Usage Examples
+
+```typescript
+// Apply to all routes
+app.use('*', timingMiddleware)
+
+// Apply to specific path
+app.use('/api/*', authMiddleware)
+
+// Apply to specific routes
+app.use('/api/admin/*', roleMiddleware('admin'))
+
+// Chain multiple middleware
+app.use('/api/*', timingMiddleware, requestIdMiddleware, authMiddleware)
+```
+
+## Quality Checklist
+
+- [ ] Uses `createMiddleware` for type safety
+- [ ] Properly typed with `Env`
+- [ ] Calls `await next()` appropriately
+- [ ] Handles errors with HTTPException
+- [ ] Variables added to bindings type
+- [ ] Exported from barrel file
+
+Now ask the user what middleware they want to create!