@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/hono/commands/project-init.md

@@ -0,0 +1,306 @@
+---
+name: project-init
+description: Initialize a new Hono project with Bun or Cloudflare Workers
+---
+
+# Initialize Hono Project
+
+Create a new Hono project with proper structure and configuration.
+
+## Workflow
+
+### Step 1: Choose Template
+
+Ask the user which template to use:
+
+1. **Bun + Cloudflare Workers** (Recommended)
+   - Development with Bun's hot reload
+   - Deployment to Cloudflare Workers
+   - D1 database, KV, R2 support
+
+2. **Bun Standalone**
+   - Pure Bun runtime
+   - Local development and deployment
+   - Bun SQLite for database
+
+3. **Cloudflare Workers Only**
+   - Wrangler for dev and deploy
+   - Full CF ecosystem
+
+### Step 2: Create Project
+
+#### Template: Bun + Cloudflare Workers
+
+```bash
+# Create project directory
+mkdir {project-name} && cd {project-name}
+
+# Initialize with Bun
+bun init -y
+
+# Install dependencies
+bun add hono @hono/zod-validator zod
+bun add -d @cloudflare/workers-types wrangler typescript
+```
+
+**package.json:**
+```json
+{
+  "name": "{project-name}",
+  "scripts": {
+    "dev": "bun run --hot src/index.ts",
+    "dev:cf": "wrangler dev src/index.ts",
+    "deploy": "wrangler deploy",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "hono": "^4.0.0",
+    "@hono/zod-validator": "^0.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.0.0",
+    "typescript": "^5.0.0",
+    "wrangler": "^3.0.0"
+  }
+}
+```
+
+**tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["@cloudflare/workers-types", "bun-types"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+**wrangler.toml:**
+```toml
+name = "{project-name}"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+ENVIRONMENT = "production"
+
+# Uncomment to enable D1
+# [[d1_databases]]
+# binding = "DB"
+# database_name = "{project-name}-db"
+# database_id = "your-database-id"
+
+# Uncomment to enable KV
+# [[kv_namespaces]]
+# binding = "KV"
+# id = "your-kv-id"
+
+# Uncomment to enable R2
+# [[r2_buckets]]
+# binding = "BUCKET"
+# bucket_name = "{project-name}-bucket"
+```
+
+### Step 3: Create Directory Structure
+
+```
+{project-name}/
+├── src/
+│   ├── routes/
+│   │   └── index.ts
+│   ├── middleware/
+│   │   └── index.ts
+│   ├── validators/
+│   │   └── index.ts
+│   ├── types/
+│   │   └── bindings.ts
+│   ├── lib/
+│   │   └── errors.ts
+│   └── index.ts
+├── tests/
+│   └── index.test.ts
+├── .dev.vars
+├── .gitignore
+├── package.json
+├── tsconfig.json
+└── wrangler.toml
+```
+
+### Step 4: Create Core Files
+
+**src/types/bindings.ts:**
+```typescript
+export type Env = {
+  Bindings: {
+    // Cloudflare bindings (uncomment as needed)
+    // DB: D1Database
+    // KV: KVNamespace
+    // BUCKET: R2Bucket
+
+    // Environment variables
+    ENVIRONMENT: string
+    // JWT_SECRET: string
+  }
+  Variables: {
+    // Request-scoped variables
+    requestId: string
+  }
+}
+```
+
+**src/index.ts:**
+```typescript
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { secureHeaders } from 'hono/secure-headers'
+import type { Env } from './types/bindings'
+
+const app = new Hono<Env>()
+
+// Global middleware
+app.use('*', logger())
+app.use('*', secureHeaders())
+app.use('*', cors({
+  origin: ['http://localhost:3000'],
+  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowHeaders: ['Content-Type', 'Authorization'],
+}))
+
+// Request ID middleware
+app.use('*', async (c, next) => {
+  c.set('requestId', crypto.randomUUID())
+  await next()
+})
+
+// Health check
+app.get('/health', (c) => {
+  return c.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    requestId: c.get('requestId')
+  })
+})
+
+// 404 handler
+app.notFound((c) => {
+  return c.json({ error: 'Not found' }, 404)
+})
+
+// Error handler
+app.onError((err, c) => {
+  console.error(`Error: ${err.message}`)
+  return c.json({ error: 'Internal server error' }, 500)
+})
+
+export default app
+
+// Export type for RPC client
+export type AppType = typeof app
+```
+
+**src/lib/errors.ts:**
+```typescript
+import { HTTPException } from 'hono/http-exception'
+
+export class NotFoundError extends HTTPException {
+  constructor(resource: string) {
+    super(404, { message: `${resource} not found` })
+  }
+}
+
+export class UnauthorizedError extends HTTPException {
+  constructor(message = 'Unauthorized') {
+    super(401, { message })
+  }
+}
+
+export class ValidationError extends HTTPException {
+  constructor(message: string) {
+    super(400, { message })
+  }
+}
+```
+
+**tests/index.test.ts:**
+```typescript
+import { describe, it, expect } from 'bun:test'
+import app from '../src/index'
+
+describe('Health Check', () => {
+  it('returns ok status', async () => {
+    const res = await app.request('/health')
+
+    expect(res.status).toBe(200)
+
+    const data = await res.json()
+    expect(data.status).toBe('ok')
+    expect(data.requestId).toBeDefined()
+  })
+})
+
+describe('404 Handler', () => {
+  it('returns 404 for unknown routes', async () => {
+    const res = await app.request('/unknown-route')
+
+    expect(res.status).toBe(404)
+  })
+})
+```
+
+**.dev.vars:**
+```
+# Local development secrets (not committed)
+# JWT_SECRET=your-secret-here
+```
+
+**.gitignore:**
+```
+node_modules/
+.wrangler/
+.dev.vars
+*.log
+dist/
+.DS_Store
+```
+
+### Step 5: Verify Setup
+
+```bash
+# Run tests
+bun test
+
+# Start development server
+bun run dev
+
+# Test health endpoint
+curl http://localhost:3000/health
+```
+
+## Quality Checklist
+
+- [ ] Dependencies installed
+- [ ] TypeScript configured with strict mode
+- [ ] Wrangler configured for deployment
+- [ ] Basic middleware set up
+- [ ] Error handling configured
+- [ ] Health endpoint working
+- [ ] Tests passing
+- [ ] Git initialized with .gitignore
+
+Now ask the user what project they want to create!

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

@@ -0,0 +1,153 @@
+---
+name: route-create
+description: Create a new Hono route with handlers, validators, and types
+---
+
+# Create Hono Route
+
+Create a new Hono route following project conventions.
+
+## Workflow
+
+### Step 1: Gather Requirements
+
+Ask the user:
+1. **Resource name** (e.g., "users", "posts", "orders")
+2. **Operations needed** (GET list, GET single, POST, PUT, DELETE)
+3. **Fields/schema** for the resource
+4. **Relationships** to other resources
+5. **Authentication** requirements
+
+### Step 2: Create Zod Schema
+
+Create validator file first:
+
+```typescript
+// validators/{resource}.schema.ts
+import { z } from 'zod'
+
+export const create{Resource}Schema = z.object({
+  // Fields based on user requirements
+})
+
+export const update{Resource}Schema = create{Resource}Schema.partial()
+
+export const {resource}ParamsSchema = z.object({
+  id: z.string().uuid(),
+})
+
+export const {resource}QuerySchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+})
+
+// Export types
+export type Create{Resource} = z.infer<typeof create{Resource}Schema>
+export type Update{Resource} = z.infer<typeof update{Resource}Schema>
+```
+
+### Step 3: Create Route File
+
+```typescript
+// routes/{resource}.ts
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import type { Env } from '../types/bindings'
+import {
+  create{Resource}Schema,
+  update{Resource}Schema,
+  {resource}ParamsSchema,
+  {resource}QuerySchema
+} from '../validators/{resource}.schema'
+
+const {resource} = new Hono<Env>()
+
+// GET /{resource} - List
+{resource}.get('/',
+  zValidator('query', {resource}QuerySchema),
+  async (c) => {
+    const { page, limit } = c.req.valid('query')
+    // Implementation
+    return c.json({ data: [], meta: { page, limit } })
+  }
+)
+
+// GET /{resource}/:id - Get single
+{resource}.get('/:id',
+  zValidator('param', {resource}ParamsSchema),
+  async (c) => {
+    const { id } = c.req.valid('param')
+    // Implementation
+    return c.json({ id })
+  }
+)
+
+// POST /{resource} - Create
+{resource}.post('/',
+  zValidator('json', create{Resource}Schema),
+  async (c) => {
+    const data = c.req.valid('json')
+    // Implementation
+    return c.json({ id: crypto.randomUUID(), ...data }, 201)
+  }
+)
+
+// PUT /{resource}/:id - Update
+{resource}.put('/:id',
+  zValidator('param', {resource}ParamsSchema),
+  zValidator('json', update{Resource}Schema),
+  async (c) => {
+    const { id } = c.req.valid('param')
+    const data = c.req.valid('json')
+    // Implementation
+    return c.json({ id, ...data })
+  }
+)
+
+// DELETE /{resource}/:id - Delete
+{resource}.delete('/:id',
+  zValidator('param', {resource}ParamsSchema),
+  async (c) => {
+    const { id } = c.req.valid('param')
+    // Implementation
+    return c.body(null, 204)
+  }
+)
+
+export { {resource} }
+```
+
+### Step 4: Mount Route
+
+Update `src/index.ts`:
+
+```typescript
+import { {resource} } from './routes/{resource}'
+
+// Mount route
+app.route('/api/{resource}', {resource})
+```
+
+### Step 5: Update Types (if using RPC)
+
+```typescript
+// Ensure AppType is exported for RPC client
+export type AppType = typeof app
+```
+
+## Generated Files
+
+1. `validators/{resource}.schema.ts` - Zod schemas
+2. `routes/{resource}.ts` - Route handlers
+3. Updated `src/index.ts` - Route mounting
+
+## Quality Checklist
+
+- [ ] All handlers have Zod validation
+- [ ] Proper HTTP status codes (200, 201, 204, 400, 404)
+- [ ] Types exported for RPC
+- [ ] Consistent response format
+- [ ] Error handling included
+- [ ] Route mounted in main app
+
+Now ask the user what route they want to create!

package/packs/hono/commands/rpc-client.md

@@ -0,0 +1,263 @@
+---
+name: rpc-client
+description: Generate type-safe RPC client from Hono server routes
+---
+
+# Generate Hono RPC Client
+
+Create a type-safe client for your Hono API using the `hc` client.
+
+## Workflow
+
+### Step 1: Verify Server Setup
+
+Check that the server exports the app type:
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+// ... routes ...
+
+export default app
+
+// REQUIRED: Export type for RPC client
+export type AppType = typeof app
+```
+
+### Step 2: Create Client Package
+
+For monorepo or separate client package:
+
+```bash
+# If using monorepo with workspaces
+mkdir -p packages/api-client
+cd packages/api-client
+bun init -y
+bun add hono
+```
+
+**packages/api-client/package.json:**
+```json
+{
+  "name": "@{project}/api-client",
+  "version": "1.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "hono": "^4.0.0"
+  }
+}
+```
+
+### Step 3: Create Client
+
+**packages/api-client/src/index.ts:**
+```typescript
+import { hc } from 'hono/client'
+import type { AppType } from '@{project}/api/src/index'
+
+// Create typed client
+export const createApiClient = (baseUrl: string) => {
+  return hc<AppType>(baseUrl)
+}
+
+// Default client for common use
+export const api = createApiClient(
+  process.env.API_URL || 'http://localhost:8787'
+)
+
+// Re-export types for consumers
+export type { AppType }
+
+// Export inferred types for convenience
+export type ApiClient = ReturnType<typeof createApiClient>
+```
+
+### Step 4: Usage Examples
+
+**Basic Usage:**
+```typescript
+import { api } from '@{project}/api-client'
+
+// GET request
+const users = await api.api.users.$get()
+const data = await users.json()
+
+// POST request with body
+const newUser = await api.api.users.$post({
+  json: {
+    email: 'user@example.com',
+    name: 'New User'
+  }
+})
+
+// GET with query params
+const searchResults = await api.api.users.$get({
+  query: {
+    page: 1,
+    limit: 10,
+    search: 'john'
+  }
+})
+
+// GET with path params
+const user = await api.api.users[':id'].$get({
+  param: { id: 'user-uuid' }
+})
+
+// PUT with params and body
+const updated = await api.api.users[':id'].$put({
+  param: { id: 'user-uuid' },
+  json: { name: 'Updated Name' }
+})
+
+// DELETE
+await api.api.users[':id'].$delete({
+  param: { id: 'user-uuid' }
+})
+```
+
+**With Error Handling:**
+```typescript
+import { api } from '@{project}/api-client'
+
+async function getUser(id: string) {
+  const res = await api.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()
+}
+```
+
+**With Headers:**
+```typescript
+import { hc } from 'hono/client'
+import type { AppType } from '@{project}/api/src/index'
+
+const api = hc<AppType>('http://localhost:8787', {
+  headers: {
+    Authorization: `Bearer ${token}`
+  }
+})
+
+// Or per-request headers
+const res = await api.api.users.$get({
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+})
+```
+
+**React Query Integration:**
+```typescript
+import { useQuery, useMutation } from '@tanstack/react-query'
+import { api } from '@{project}/api-client'
+
+// Query hook
+export function useUsers(page = 1) {
+  return useQuery({
+    queryKey: ['users', page],
+    queryFn: async () => {
+      const res = await api.api.users.$get({
+        query: { page, limit: 20 }
+      })
+      if (!res.ok) throw new Error('Failed to fetch users')
+      return res.json()
+    }
+  })
+}
+
+// Mutation hook
+export function useCreateUser() {
+  return useMutation({
+    mutationFn: async (data: { email: string; name: string }) => {
+      const res = await api.api.users.$post({ json: data })
+      if (!res.ok) throw new Error('Failed to create user')
+      return res.json()
+    }
+  })
+}
+```
+
+### Step 5: TypeScript Configuration
+
+Ensure both server and client have matching TypeScript settings:
+
+**tsconfig.json (both projects):**
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+## Type Inference
+
+The client automatically infers:
+- Request body types from Zod validators
+- Response types from handler return values
+- Query parameter types
+- Path parameter types
+
+```typescript
+// Server: defines the contract
+app.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: '123', ...data }, 201)
+  }
+)
+
+// Client: types are inferred!
+const res = await api.api.users.$post({
+  json: {
+    email: 'user@example.com',  // typed as string
+    name: 'User'                 // typed as string
+  }
+})
+const user = await res.json()
+// user is typed as { id: string; email: string; name: string }
+```
+
+## URL Generation
+
+```typescript
+import { api } from '@{project}/api-client'
+
+// Generate URL without making request
+const url = api.api.users[':id'].$url({
+  param: { id: 'user-123' }
+})
+// url = 'http://localhost:8787/api/users/user-123'
+```
+
+## Quality Checklist
+
+- [ ] Server exports `AppType`
+- [ ] `strict: true` in both tsconfigs
+- [ ] Client properly typed
+- [ ] Error handling implemented
+- [ ] Headers configured (auth, etc.)
+- [ ] Works with React Query (if using)
+
+Now set up the RPC client for your project!

package/packs/hono/hooks/hooks.json

@@ -0,0 +1,4 @@
+{
+  "description": "Hono hooks - currently empty (convention enforcement handled by skills)",
+  "hooks": {}
+}