@riligar/agents-kit 1.10.0 → 1.12.0

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

@@ -0,0 +1,224 @@
+# Elysia Basics
+
+## Installation
+
+```bash
+bun add elysia
+```
+
+## Minimal Server
+
+```javascript
+import { Elysia } from 'elysia'
+
+const app = new Elysia()
+    .get('/', () => 'Hello World')
+    .listen(3000)
+
+console.log(`Server running at ${app.server?.url}`)
+```
+
+## HTTP Methods
+
+```javascript
+const app = new Elysia()
+    .get('/users', () => getUsers())           // Read
+    .post('/users', ({ body }) => create(body)) // Create
+    .put('/users/:id', ({ params, body }) => replace(params.id, body))   // Replace
+    .patch('/users/:id', ({ params, body }) => update(params.id, body))  // Update
+    .delete('/users/:id', ({ params }) => remove(params.id))             // Delete
+```
+
+## Context Object
+
+Every handler receives a context object with request data:
+
+```javascript
+app.post('/example', (ctx) => {
+    // Request data
+    ctx.body      // Parsed request body
+    ctx.query     // Query string (?key=value)
+    ctx.params    // Path parameters (/:id)
+    ctx.headers   // Request headers
+    ctx.cookie    // Cookies
+    ctx.request   // Raw Request object
+    ctx.path      // Request pathname
+
+    // Response helpers
+    ctx.set.status = 201           // Set status code
+    ctx.set.headers['X-Custom'] = 'value'  // Set header
+    ctx.redirect('/other')         // Redirect
+
+    return { success: true }
+})
+```
+
+## Destructuring Context
+
+```javascript
+// Clean handler with destructuring
+app.post('/users', ({ body, set }) => {
+    const user = createUser(body)
+    set.status = 201
+    return user
+})
+
+app.get('/users/:id', ({ params }) => {
+    return getUserById(params.id)
+})
+
+app.get('/search', ({ query }) => {
+    return search(query.q, query.limit)
+})
+```
+
+## Response Types
+
+### JSON (default)
+
+```javascript
+app.get('/json', () => {
+    return { message: 'Hello' }  // Automatically JSON
+})
+```
+
+### String
+
+```javascript
+app.get('/text', () => {
+    return 'Plain text response'
+})
+```
+
+### Status Codes
+
+```javascript
+app.post('/users', ({ body, set }) => {
+    const user = createUser(body)
+    set.status = 201  // Created
+    return user
+})
+
+app.get('/users/:id', ({ params, set }) => {
+    const user = findUser(params.id)
+    if (!user) {
+        set.status = 404
+        return { error: 'User not found' }
+    }
+    return user
+})
+```
+
+### Redirect
+
+```javascript
+app.get('/old-path', ({ redirect }) => {
+    return redirect('/new-path')
+})
+```
+
+## Route Parameters
+
+### Path Parameters
+
+```javascript
+// Single parameter
+app.get('/users/:id', ({ params }) => {
+    return getUserById(params.id)
+})
+
+// Multiple parameters
+app.get('/users/:userId/posts/:postId', ({ params }) => {
+    return getPost(params.userId, params.postId)
+})
+```
+
+### Query Parameters
+
+```javascript
+// GET /search?q=hello&limit=10
+app.get('/search', ({ query }) => {
+    const { q, limit = '10' } = query
+    return search(q, parseInt(limit))
+})
+```
+
+## Headers
+
+### Reading Headers
+
+```javascript
+app.get('/protected', ({ headers, set }) => {
+    const token = headers.authorization
+    if (!token) {
+        set.status = 401
+        return { error: 'Unauthorized' }
+    }
+    return { message: 'Welcome' }
+})
+```
+
+### Setting Headers
+
+```javascript
+app.get('/api/data', ({ set }) => {
+    set.headers['X-Custom-Header'] = 'value'
+    set.headers['Cache-Control'] = 'max-age=3600'
+    return { data: 'example' }
+})
+```
+
+## Cookies
+
+```javascript
+app.get('/set-cookie', ({ cookie }) => {
+    cookie.session.set({
+        value: 'abc123',
+        httpOnly: true,
+        maxAge: 60 * 60 * 24  // 1 day
+    })
+    return { message: 'Cookie set' }
+})
+
+app.get('/read-cookie', ({ cookie }) => {
+    return { session: cookie.session.value }
+})
+```
+
+## Static Files
+
+```javascript
+import { Elysia } from 'elysia'
+import { staticPlugin } from '@elysiajs/static'
+
+const app = new Elysia()
+    .use(staticPlugin({
+        prefix: '/public',
+        assets: 'public'
+    }))
+```
+
+## Environment Variables
+
+```javascript
+// Use Bun's built-in env
+const port = process.env.PORT || 3000
+const dbUrl = process.env.DATABASE_URL
+
+const app = new Elysia()
+    .listen(port)
+```
+
+## Graceful Shutdown
+
+```javascript
+const app = new Elysia()
+    .get('/', () => 'Hello')
+    .listen(3000)
+
+process.on('SIGINT', () => {
+    console.log('Shutting down...')
+    app.stop()
+    process.exit(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
+```