@riligar/agents-kit 1.11.0 → 1.12.0

package/.agent/skills/riligar-dev-backend/references/elysia-lifecycle.md

@@ -0,0 +1,268 @@
+# Elysia Lifecycle Hooks
+
+Lifecycle hooks allow you to intercept requests at different stages. They're the foundation for middleware, auth, logging, and error handling.
+
+## Lifecycle Order
+
+```
+Request → onRequest → onParse → onBeforeHandle → Handler → onAfterHandle → onAfterResponse
+                                      ↓
+                                   onError (if error thrown)
+```
+
+## onRequest
+
+First hook executed. Minimal context, best for early checks.
+
+```javascript
+const app = new Elysia()
+    .onRequest(({ request }) => {
+        console.log(`${request.method} ${request.url}`)
+    })
+```
+
+**Use cases:**
+- Request logging
+- Rate limiting
+- IP blocking
+- CORS headers
+
+**Early return skips remaining lifecycle:**
+
+```javascript
+.onRequest(({ request, set }) => {
+    if (isBlocked(request)) {
+        set.status = 403
+        return { error: 'Forbidden' }
+    }
+})
+```
+
+## onBeforeHandle
+
+Runs after validation, before handler. Has full context.
+
+```javascript
+const app = new Elysia()
+    .onBeforeHandle(({ headers, set }) => {
+        if (!headers.authorization) {
+            set.status = 401
+            return { error: 'Unauthorized' }
+        }
+    })
+```
+
+**Use cases:**
+- Authentication checks
+- Authorization
+- Custom validation
+- Request transformation
+
+## onAfterHandle
+
+Runs after handler, can transform response.
+
+```javascript
+const app = new Elysia()
+    .onAfterHandle(({ response, set }) => {
+        // Add header to all responses
+        set.headers['X-Powered-By'] = 'Elysia'
+
+        // Transform response
+        if (typeof response === 'object') {
+            return {
+                success: true,
+                data: response,
+                timestamp: Date.now()
+            }
+        }
+    })
+```
+
+**Use cases:**
+- Response transformation
+- Adding headers
+- Logging response
+
+## onError
+
+Catches any error thrown during lifecycle.
+
+```javascript
+const app = new Elysia()
+    .onError(({ code, error, set }) => {
+        console.error(error)
+
+        switch (code) {
+            case 'VALIDATION':
+                set.status = 422
+                return { error: 'Validation failed', details: error.all }
+
+            case 'NOT_FOUND':
+                set.status = 404
+                return { error: 'Not found' }
+
+            default:
+                set.status = 500
+                return { error: 'Internal server error' }
+        }
+    })
+```
+
+**Error codes:**
+- `VALIDATION` - Schema validation failed
+- `NOT_FOUND` - Route not found
+- `PARSE` - Body parsing failed
+- `INTERNAL_SERVER_ERROR` - Unhandled error
+- `UNKNOWN` - Unknown error type
+
+## onAfterResponse
+
+Runs after response is sent. Cannot modify response.
+
+```javascript
+const app = new Elysia()
+    .onAfterResponse(({ request, set }) => {
+        console.log(`Completed: ${request.method} ${request.url} - ${set.status}`)
+    })
+```
+
+**Use cases:**
+- Logging
+- Analytics
+- Cleanup
+
+## Local vs Interceptor Hooks
+
+### Local Hook (single route)
+
+```javascript
+app.get('/users', () => getUsers(), {
+    beforeHandle: ({ headers, set }) => {
+        if (!headers.authorization) {
+            set.status = 401
+            return { error: 'Unauthorized' }
+        }
+    }
+})
+```
+
+### Interceptor Hook (all subsequent routes)
+
+```javascript
+const app = new Elysia()
+    .onBeforeHandle(() => console.log('Runs on all routes below'))
+    .get('/a', () => 'A')  // Hook runs
+    .get('/b', () => 'B')  // Hook runs
+```
+
+## Practical Examples
+
+### Authentication Middleware
+
+```javascript
+const requireAuth = ({ headers, set }) => {
+    const token = headers.authorization?.replace('Bearer ', '')
+
+    if (!token) {
+        set.status = 401
+        return { error: 'Missing token' }
+    }
+
+    try {
+        const user = verifyToken(token)
+        // User available in handler
+    } catch {
+        set.status = 401
+        return { error: 'Invalid token' }
+    }
+}
+
+const app = new Elysia()
+    // Public routes
+    .get('/health', () => ({ status: 'ok' }))
+
+    // Protected routes
+    .guard({ beforeHandle: requireAuth }, app => app
+        .get('/profile', () => getProfile())
+        .put('/profile', ({ body }) => updateProfile(body))
+    )
+```
+
+### Request Logging
+
+```javascript
+const logger = new Elysia({ name: 'logger' })
+    .onRequest(({ request }) => {
+        const start = Date.now()
+        request.startTime = start
+    })
+    .onAfterResponse(({ request, set }) => {
+        const duration = Date.now() - request.startTime
+        console.log(`${request.method} ${request.url} ${set.status} ${duration}ms`)
+    })
+
+app.use(logger)
+```
+
+### Error Wrapper
+
+```javascript
+const app = new Elysia()
+    .onError(({ code, error, path, set }) => {
+        // Log error
+        console.error({
+            path,
+            code,
+            message: error.message,
+            stack: error.stack
+        })
+
+        // Don't expose internal errors
+        if (code === 'INTERNAL_SERVER_ERROR') {
+            set.status = 500
+            return {
+                error: 'Something went wrong',
+                requestId: generateRequestId()
+            }
+        }
+
+        // Validation errors - expose details
+        if (code === 'VALIDATION') {
+            set.status = 422
+            return {
+                error: 'Validation failed',
+                details: error.all
+            }
+        }
+    })
+```
+
+### Rate Limiting
+
+```javascript
+const rateLimits = new Map()
+
+const rateLimit = (limit = 100, windowMs = 60000) => {
+    return new Elysia({ name: 'rate-limit' })
+        .onRequest(({ request, set }) => {
+            const ip = request.headers.get('x-forwarded-for') || 'unknown'
+            const now = Date.now()
+            const windowStart = now - windowMs
+
+            const requests = rateLimits.get(ip) || []
+            const recentRequests = requests.filter(t => t > windowStart)
+
+            if (recentRequests.length >= limit) {
+                set.status = 429
+                set.headers['Retry-After'] = Math.ceil(windowMs / 1000)
+                return { error: 'Too many requests' }
+            }
+
+            recentRequests.push(now)
+            rateLimits.set(ip, recentRequests)
+        })
+}
+
+app.use(rateLimit(100, 60000))  // 100 requests per minute
+```

package/.agent/skills/riligar-dev-backend/references/elysia-patterns.md

@@ -0,0 +1,324 @@
+# Elysia API Patterns
+
+## REST Resource Naming
+
+```
+Rules:
+├── Use NOUNS, not verbs (resources, not actions)
+├── Use PLURAL forms (/users not /user)
+├── Use lowercase with hyphens (/user-profiles)
+├── Nest for relationships (/users/123/posts)
+└── Keep shallow (max 3 levels deep)
+```
+
+### Examples
+
+```javascript
+// Good
+GET    /users           // List users
+GET    /users/:id       // Get user
+POST   /users           // Create user
+PUT    /users/:id       // Replace user
+PATCH  /users/:id       // Update user
+DELETE /users/:id       // Delete user
+
+GET    /users/:id/posts         // User's posts
+POST   /users/:id/posts         // Create post for user
+
+// Bad
+GET    /getUsers
+POST   /createUser
+GET    /users/123/posts/456/comments/789/likes  // Too deep
+```
+
+## HTTP Status Codes
+
+| Situation | Code | When |
+| --- | --- | --- |
+| Success (read) | `200` | GET succeeded |
+| Created | `201` | POST created resource |
+| No content | `204` | DELETE succeeded |
+| Bad request | `400` | Malformed request |
+| Unauthorized | `401` | Missing/invalid auth |
+| Forbidden | `403` | Valid auth, no permission |
+| Not found | `404` | Resource doesn't exist |
+| Conflict | `409` | State conflict (duplicate) |
+| Validation error | `422` | Valid syntax, invalid data |
+| Rate limited | `429` | Too many requests |
+| Server error | `500` | Unhandled error |
+
+## Response Patterns
+
+### Success Response
+
+```javascript
+// Single resource
+app.get('/users/:id', ({ params, set }) => {
+    const user = getUserById(params.id)
+    if (!user) {
+        set.status = 404
+        return { error: 'User not found' }
+    }
+    return user
+})
+
+// List response
+app.get('/users', () => {
+    return {
+        data: getUsers(),
+        total: getUserCount()
+    }
+})
+
+// Created response
+app.post('/users', ({ body, set }) => {
+    const user = createUser(body)
+    set.status = 201
+    return user
+})
+
+// No content response
+app.delete('/users/:id', ({ params, set }) => {
+    deleteUser(params.id)
+    set.status = 204
+})
+```
+
+### Error Response
+
+```javascript
+// Consistent error format
+const errorResponse = (message, code, details = null) => ({
+    error: {
+        message,
+        code,
+        details
+    }
+})
+
+app.get('/users/:id', ({ params, set }) => {
+    const user = getUserById(params.id)
+    if (!user) {
+        set.status = 404
+        return errorResponse('User not found', 'USER_NOT_FOUND')
+    }
+    return user
+})
+```
+
+## Pagination
+
+### Offset Pagination
+
+```javascript
+import { Elysia, t } from 'elysia'
+
+app.get('/users', ({ query }) => {
+    const { page = 1, limit = 10 } = query
+    const offset = (page - 1) * limit
+
+    const users = getUsers({ offset, limit })
+    const total = getUserCount()
+
+    return {
+        data: users,
+        pagination: {
+            page,
+            limit,
+            total,
+            totalPages: Math.ceil(total / limit)
+        }
+    }
+}, {
+    query: t.Object({
+        page: t.Optional(t.Numeric({ default: 1, minimum: 1 })),
+        limit: t.Optional(t.Numeric({ default: 10, minimum: 1, maximum: 100 }))
+    })
+})
+```
+
+### Cursor Pagination
+
+```javascript
+app.get('/posts', ({ query }) => {
+    const { cursor, limit = 10 } = query
+
+    const posts = getPosts({ cursor, limit: limit + 1 })
+    const hasMore = posts.length > limit
+    const data = hasMore ? posts.slice(0, -1) : posts
+    const nextCursor = hasMore ? data[data.length - 1].id : null
+
+    return {
+        data,
+        pagination: {
+            nextCursor,
+            hasMore
+        }
+    }
+}, {
+    query: t.Object({
+        cursor: t.Optional(t.String()),
+        limit: t.Optional(t.Numeric({ default: 10, maximum: 100 }))
+    })
+})
+```
+
+## Filtering & Sorting
+
+```javascript
+app.get('/products', ({ query }) => {
+    const { category, minPrice, maxPrice, sort = 'createdAt', order = 'desc' } = query
+
+    return getProducts({
+        filters: {
+            category,
+            price: { min: minPrice, max: maxPrice }
+        },
+        sort: { field: sort, order }
+    })
+}, {
+    query: t.Object({
+        category: t.Optional(t.String()),
+        minPrice: t.Optional(t.Numeric()),
+        maxPrice: t.Optional(t.Numeric()),
+        sort: t.Optional(t.Union([
+            t.Literal('createdAt'),
+            t.Literal('price'),
+            t.Literal('name')
+        ])),
+        order: t.Optional(t.Union([
+            t.Literal('asc'),
+            t.Literal('desc')
+        ]))
+    })
+})
+```
+
+## CRUD Resource Pattern
+
+```javascript
+// routes/users.js
+import { Elysia, t } from 'elysia'
+import * as userService from '../services/user'
+
+const UserSchema = t.Object({
+    name: t.String({ minLength: 1 }),
+    email: t.String({ format: 'email' })
+})
+
+const UserUpdateSchema = t.Partial(UserSchema)
+
+export const userRoutes = new Elysia({ prefix: '/users' })
+    // List
+    .get('/', ({ query }) => {
+        return userService.findAll(query)
+    }, {
+        query: t.Object({
+            page: t.Optional(t.Numeric({ default: 1 })),
+            limit: t.Optional(t.Numeric({ default: 10 }))
+        })
+    })
+
+    // Get by ID
+    .get('/:id', ({ params, set }) => {
+        const user = userService.findById(params.id)
+        if (!user) {
+            set.status = 404
+            return { error: 'User not found' }
+        }
+        return user
+    }, {
+        params: t.Object({ id: t.Numeric() })
+    })
+
+    // Create
+    .post('/', ({ body, set }) => {
+        const user = userService.create(body)
+        set.status = 201
+        return user
+    }, {
+        body: UserSchema
+    })
+
+    // Update
+    .patch('/:id', ({ params, body, set }) => {
+        const user = userService.update(params.id, body)
+        if (!user) {
+            set.status = 404
+            return { error: 'User not found' }
+        }
+        return user
+    }, {
+        params: t.Object({ id: t.Numeric() }),
+        body: UserUpdateSchema
+    })
+
+    // Delete
+    .delete('/:id', ({ params, set }) => {
+        const deleted = userService.remove(params.id)
+        if (!deleted) {
+            set.status = 404
+            return { error: 'User not found' }
+        }
+        set.status = 204
+    }, {
+        params: t.Object({ id: t.Numeric() })
+    })
+```
+
+## API Versioning
+
+### URL Prefix (Recommended)
+
+```javascript
+const v1Routes = new Elysia({ prefix: '/api/v1' })
+    .use(userRoutesV1)
+    .use(postRoutesV1)
+
+const v2Routes = new Elysia({ prefix: '/api/v2' })
+    .use(userRoutesV2)
+
+const app = new Elysia()
+    .use(v1Routes)
+    .use(v2Routes)
+```
+
+## Response Headers
+
+```javascript
+// CORS
+app.onRequest(({ set }) => {
+    set.headers['Access-Control-Allow-Origin'] = '*'
+    set.headers['Access-Control-Allow-Methods'] = 'GET, POST, PUT, PATCH, DELETE'
+})
+
+// Cache Control
+app.get('/static-data', ({ set }) => {
+    set.headers['Cache-Control'] = 'public, max-age=3600'
+    return getStaticData()
+})
+
+// Rate Limit Headers
+app.onAfterHandle(({ set }) => {
+    set.headers['X-RateLimit-Limit'] = '100'
+    set.headers['X-RateLimit-Remaining'] = '99'
+})
+```
+
+## Health Check
+
+```javascript
+app.get('/health', () => ({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime()
+}))
+
+app.get('/health/ready', async () => {
+    const dbOk = await checkDatabase()
+    return {
+        status: dbOk ? 'ok' : 'error',
+        database: dbOk
+    }
+})
+```