miolo 3.0.0-beta.21 → 3.0.0-beta.210

package/template/.agent/skills/miolo-routing/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: miolo-routing
+description: API routing patterns for miolo applications. Use when creating or modifying API endpoints, registering routes, handling HTTP requests, or structuring server-side route handlers in miolo apps. For validation schemas, see miolo-schemas skill.
+---
+
+# Miolo Routing Patterns
+
+Standard patterns for creating API routes in miolo applications following miolo conventions.
+
+## Route Organization
+
+Routes are organized in `src/server/routes/` by domain/feature:
+
+```
+src/server/routes/
+├── index.mjs          # Route registration array
+├── users/             # User-related endpoints
+│   └── user.mjs
+├── todos/             # Todo endpoints  
+│   ├── mod.mjs        # CRUD operations
+│   ├── read.mjs       # Read queries
+│   └── special.mjs    # Special operations
+└── [feature]/         # Additional feature routes
+```
+
+## Route Registration Pattern
+
+All routes are registered in `src/server/routes/index.mjs` using miolo's route array format:
+
+```javascript
+import { r_item_list, r_item_find } from './items/read.mjs'
+import { r_item_upsave, r_item_delete } from './items/mod.mjs'
+
+const auth = {
+  require: true,
+  action: 'redirect',
+  redirect_url: '/page/login'
+}
+
+export default [{
+  prefix: 'api',
+  routes: [
+    { method: 'GET',  url: '/item/list',   auth, callback: r_item_list },
+    { method: 'GET',  url: '/item/find',   auth, callback: r_item_find },
+    { method: 'POST', url: '/item/save',   auth, callback: r_item_upsave },
+    { method: 'POST', url: '/item/delete', auth, callback: r_item_delete },
+  ]
+}]
+```
+
+**Key elements:**
+- Export default array of route groups
+- Each group has `prefix` and `routes` array
+- Each route has `method`, `url`, optional `auth`, and `callback`
+- Import route handler functions from feature files
+
+## Creating Route Handlers
+
+### Basic Handler Structure
+
+Route handlers receive `(ctx, params)` and return `{ ok, data }` or `{ ok, error }`:
+
+```javascript
+import { db_item_read } from '#server/io/db/items/read.mjs'
+
+export async function r_item_list(ctx, params) {
+  try {
+    ctx.miolo.logger.info('[r_item_list] Fetching items')
+    
+    const items = await db_item_read(ctx, params)
+    
+    ctx.miolo.logger.info('[r_item_list] Found items')
+    return { ok: true, data: items }
+    
+  } catch (error) {
+    ctx.miolo.logger.error(`[r_item_list] Error: ${error}`)
+    return { ok: false, error: error?.message }
+  }
+}
+```
+
+**Handler conventions:**
+- Function names start with `r_` (route)
+- Take `(ctx, params)` as arguments
+- Return object with `ok` boolean
+- Include `data` on success, `error` on failure
+- Use `ctx.miolo.logger` for logging (`info` level)
+- Wrap in try/catch
+
+### Accessing Request Data
+
+```javascript
+export async function r_item_find(ctx, params) {
+  // params contains:
+  // - URL query parameters (?foo=bar)
+  // - POST body data
+  // - Already validated if schema provided
+  
+  const { id } = params
+  
+  // Access user from context
+  const user = ctx.state.user
+  
+  // Access logger
+  ctx.miolo.logger.info(`User ${user.id} requesting item ${id}`)
+  
+  return { ok: true, data: item }
+}
+```
+
+### CRUD Operations Example
+
+Complete CRUD implementation:
+
+```javascript
+// items/mod.mjs
+import { db_item_upsave } from '#server/io/db/items/upsave.mjs'
+import { db_item_delete } from '#server/io/db/items/delete.mjs'
+
+export async function r_item_upsave(ctx, params) {
+  try {
+    ctx.miolo.logger.info(`[r_item_upsave] Saving item ${params?.id || 'new'}`)
+    
+    const item = await db_item_upsave(ctx, params)
+    
+    ctx.miolo.logger.info(`[r_item_upsave] Saved item ${item.id}`)
+    return { ok: true, data: item }
+    
+  } catch (error) {
+    ctx.miolo.logger.error(`[r_item_upsave] Error: ${error}`)
+    return { ok: false, error: error?.message }
+  }
+}
+
+export async function r_item_delete(ctx, params) {
+  try {
+    ctx.miolo.logger.info(`[r_item_delete] Deleting item ${params.id}`)
+    
+    await db_item_delete(ctx, params)
+    
+    ctx.miolo.logger.info(`[r_item_delete] Deleted item ${params.id}`)
+    return { ok: true, data: { deleted: true } }
+    
+  } catch (error) {
+    ctx.miolo.logger.error(`[r_item_delete] Error: ${error}`)
+    return { ok: false, error: error?.message }
+  }
+}
+```
+
+### Request Validation with Joi
+
+Add schema validation inline or as wrapper:
+
+**Inline schema:**
+```javascript
+import Joi from 'joi'
+
+export default [{
+  prefix: 'api',
+  routes: [
+    {
+      method: 'GET',
+      url: '/item/search',
+      auth,
+      callback: r_item_search,
+      schema: {
+        input: Joi.object({
+          query: Joi.string().min(3).required(),
+          limit: Joi.number().min(1).max(100).default(20)
+        }),
+        output: Joi.object({
+          ok: Joi.boolean().required(),
+          data: Joi.array().items(Joi.object()).required(),
+          error: Joi.string().optional()
+        })
+      }
+    }
+  ]
+}]
+```
+
+**Wrapper function:**
+```javascript
+import { with_miolo_input_schema } from 'miolo'
+import Joi from 'joi'
+
+const itemSchema = Joi.object({
+  description: Joi.string().required(),
+  done: Joi.bool().optional().default(false)
+})
+
+export default [{
+  prefix: 'api',
+  routes: [
+    {
+      method: 'POST',
+      url: '/item/save',
+      auth,
+      callback: with_miolo_input_schema(r_item_upsave, itemSchema)
+    }
+  ]
+}]
+```
+
+## Authentication
+
+Configure authentication per route:
+
+```javascript
+// Require authentication
+const auth = {
+  require: true,
+  action: 'redirect',
+  redirect_url: '/page/login'
+}
+
+// Public route (no auth)
+{ method: 'GET', url: '/public/data', callback: r_public_data }
+
+// Protected route (with auth)
+{ method: 'GET', url: '/private/data', auth, callback: r_private_data }
+```
+
+Authenticated routes automatically have `ctx.state.user` populated.
+
+## Multi-file Organization
+
+For complex features, split into multiple files:
+
+```
+routes/todos/
+├── mod.mjs        # CRUD operations (upsave, delete, toggle)
+├── read.mjs       # Read operations (list, find)
+└── special.mjs    # Special operations (count, batch, etc.)
+```
+
+Each file exports handler functions, all registered in `routes/index.mjs`.
+
+## Common Patterns
+
+### Logging Pattern
+
+```javascript
+export async function r_item_operation(ctx, params) {
+  try {
+    ctx.miolo.logger.info(`[r_item_operation] Starting with id ${params.id}`)
+    
+    const result = await db_item_operation(ctx, params)
+    
+    ctx.miolo.logger.info(`[r_item_operation] Success for id ${params.id}`)
+    return { ok: true, data: result }
+    
+  } catch (error) {
+    ctx.miolo.logger.error(`[r_item_operation] Error for id ${params.id}: ${error}`)
+    return { ok: false, error: error?.message }
+  }
+}
+```
+
+### Error Handling
+
+```javascript
+export async function r_item_find(ctx, params) {
+  try {
+    const item = await db_item_find(ctx, params)
+    
+    if (!item) {
+      return { ok: false, error: 'Item not found' }
+    }
+    
+    return { ok: true, data: item }
+    
+  } catch (error) {
+    ctx.miolo.logger.error(`[r_item_find] Error: ${error}`)
+    return { ok: false, error: error?.message }
+  }
+}
+```
+
+## Adding a New Feature
+
+1. **Create database functions** in `src/server/io/db/feature/`:
+   ```javascript
+   // io/db/items/read.mjs
+   export async function db_item_read(ctx, params) { /* ... */ }
+   ```
+
+2. **Create route handlers** in `src/server/routes/feature/`:
+   ```javascript
+   // routes/items/mod.mjs
+   export async function r_item_list(ctx, params) { /* ... */ }
+   export async function r_item_upsave(ctx, params) { /* ... */ }
+   ```
+
+3. **Register routes** in `routes/index.mjs`:
+   ```javascript
+   import { r_item_list, r_item_upsave } from './items/mod.mjs'
+   
+   export default [{
+     prefix: 'api',
+     routes: [
+       { method: 'GET',  url: '/item/list', auth, callback: r_item_list },
+       { method: 'POST', url: '/item/save', auth, callback: r_item_upsave },
+     ]
+   }]
+   ```
+
+## Best Practices
+
+1. **Use database abstraction** - Never write SQL in routes, use `io/db/` functions
+2. **Consistent naming** - Routes start with `r_`, database functions with `db_`
+3. **Always log** - Use `ctx.miolo.logger` for all operations (`info`level)
+4. **Return consistent format** - Always `{ ok, data }` or `{ ok, error }`
+5. **Validate inputs (and outputs)** - Use Joi schemas for validation
+6. **Handle errors** - Wrap in try/catch, return meaningful errors
+7. **Check user access** - Use `ctx.state.user` to verify permissions
+8. **Keep handlers thin** - Business logic in `io/db/`, routes only handle HTTP
+
+## Examples from miolo-sample
+
+See actual implementations:
+- `src/server/routes/index.mjs` - Route registration
+- `src/server/routes/todos/mod.mjs` - CRUD handlers
+- `src/server/routes/todos/read.mjs` - Read operations
+- `src/server/routes/todos/special.mjs` - Custom operations

package/template/.agent/skills/miolo-schemas/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: miolo-schemas
+description: Joi validation schemas and patterns for miolo applications. Use when implementing request/parameter validation for routes or database functions, creating reusable schema components, or using with_miolo_input_schema and with_miolo_output_schema wrappers.
+---
+
+# Miolo Validation Schemas
+
+Joi validation schema patterns for miolo routes and database functions.
+
+## Schema Wrappers: with_miolo_input_schema and with_miolo_output_schema
+
+Use `with_miolo_input_schema` to wrap route handlers and database functions to validate incoming parameters.
+
+```javascript
+import { with_miolo_input_schema } from 'miolo'
+import Joi from 'joi'
+
+// Define schema
+const todoSchema = Joi.object({
+  id: Joi.number().integer().optional(),
+  description: Joi.string().required(),
+  done: Joi.boolean().optional().default(false)
+})
+
+// Wrap function with schema
+async function _r_todo_upsave(ctx, params) {
+  // params are already validated here
+  const { id, description, done } = params
+  // ...
+}
+
+export const r_todo_upsave = with_miolo_input_schema(_r_todo_upsave, todoSchema)
+```
+
+**Key benefits:**
+- Automatic validation before function execution (input) or before sending the response (output)
+- Validation errors handled automatically
+- Default values applied
+- Type coercion
+- Extraneous fields removed (diff log generated on output schemas)
+
+### Using `with_miolo_output_schema`
+
+Use `with_miolo_output_schema` to ensure that data returned by a function matches the expected format, automatically stripping any extra properties not defined in the schema.
+
+```javascript
+import { with_miolo_output_schema } from 'miolo'
+import Joi from 'joi'
+
+const todoOutputSchema = Joi.object({
+  ok: Joi.boolean().required(),
+  data: Joi.object({
+    id: Joi.number().required(),
+    description: Joi.string().required()
+  })
+})
+
+export const db_todo_insert = with_miolo_output_schema(_db_todo_insert, todoOutputSchema)
+```
+
+## Using Schemas in Routes
+
+Route definitions accept a `schema` object that can contain both `input` and `output` schemas:
+
+### Inline Schema (Route Definition)
+
+Define schema directly in route configuration:
+
+```javascript
+import Joi from 'joi'
+
+export default [{
+  prefix: 'api',
+  routes: [
+    {
+      method: 'GET',
+      url: '/todo/last_hours',
+      auth,
+      callback: r_todo_count_last_hours,
+      schema: {
+        input: Joi.object({
+          hours: Joi.number().min(1).max(24).required()
+        }),
+        output: Joi.object({
+          ok: Joi.boolean().required(),
+          data: Joi.number().required()
+        })
+      }
+    }
+  ]
+}]
+```
+
+### Wrapper Schema (Function)
+
+Wrap the handler function with schema:
+
+```javascript
+import { with_miolo_input_schema } from 'miolo'
+import Joi from 'joi'
+
+const todoSchema = Joi.object({
+  done: Joi.bool().optional().default(false)
+})
+
+export default [{
+  prefix: 'api',
+  routes: [
+    {
+      method: 'POST',
+      url: '/todo/fake',
+      auth,
+      callback: with_miolo_input_schema(r_todo_insert_fake, todoSchema)
+    }
+  ]
+}]
+```
+
+## Using Schemas in Database Functions
+
+**Strongly recommended** to validate database function parameters:
+
+```javascript
+import { with_miolo_input_schema } from 'miolo'
+import Joi from 'joi'
+import { opt_int, bool_null, opt_str_null } from '#server/utils/schema.mjs'
+
+// Internal implementation
+async function _db_todo_read(ctx, filter) {
+  ctx.miolo.logger.verbose('[db_todo_read] Reading todos...')
+  
+  const conn = await ctx.miolo.db.get_connection()
+  const options = { transaction: undefined }
+  
+  // ... query logic
+  
+  return todos
+}
+
+// Schema definition using partial schemas
+const todo_read_schema = Joi.object({
+  id: opt_int,
+  todo_id: opt_int,
+  description: opt_str_null,
+  done: bool_null
+})
+
+// Export wrapped function
+export const db_todo_read = with_miolo_input_schema(_db_todo_read, todo_read_schema)
+```
+
+**Pattern:**
+1. Create private implementation function with `_` prefix
+2. Define schema using partial schemas from `utils/schema.mjs`
+3. Export wrapped function with `with_miolo_input_schema`
+
+## Partial Schemas (Reusable Components)
+
+Miolo provides common validation patterns in `src/server/utils/schema.mjs`:
+
+```javascript
+import Joi from 'joi'
+
+// Integer (optional)
+export const opt_int = Joi.number().integer().optional()
+
+// String (optional, nullable)
+export const opt_str_null = Joi.string().optional().allow(null)
+
+// Boolean (nullable)
+export const bool_null = Joi.boolean().optional().allow(null)
+
+// Email
+export const email = Joi.string().email().required()
+
+// Positive integer
+export const pos_int = Joi.number().integer().min(1).required()
+
+// ... add more as needed
+```
+
+**Usage:**
+```javascript
+import { opt_int, opt_str_null, email } from '#server/utils/schema.mjs'
+
+const userSchema = Joi.object({
+  id: opt_int,
+  email: email,
+  name: opt_str_null,
+  age: pos_int
+})
+```
+
+## Common Schema Patterns
+
+### Optional vs Required
+
+```javascript
+// Required field
+description: Joi.string().required()
+
+// Optional field
+id: Joi.number().integer().optional()
+
+// Optional with default
+done: Joi.boolean().optional().default(false)
+```
+
+### Nullable Fields
+
+```javascript
+// Allow null
+name: Joi.string().allow(null).optional()
+
+// Using partial schema
+name: opt_str_null
+```
+
+### Type Validation
+
+```javascript
+// Integer
+id: Joi.number().integer()
+
+// String with min/max length
+description: Joi.string().min(3).max(500)
+
+// Email
+email: Joi.string().email()
+
+// Boolean
+active: Joi.boolean()
+
+// Array
+tags: Joi.array().items(Joi.string())
+
+// Enum
+status: Joi.string().valid('pending', 'active', 'completed')
+```
+
+### Number Constraints
+
+```javascript
+// Range
+age: Joi.number().min(18).max(100)
+
+// Positive
+count: Joi.number().positive()
+
+// Integer only
+quantity: Joi.number().integer()
+```
+
+### String Constraints
+
+```javascript
+// Min/max length
+name: Joi.string().min(3).max(50)
+
+// Pattern (regex)
+code: Joi.string().pattern(/^[A-Z]{3}[0-9]{3}$/)
+
+// Case insensitive
+email: Joi.string().email().lowercase()
+
+// Trim whitespace
+username: Joi.string().trim()
+```
+
+### Conditional Validation
+
+```javascript
+const schema = Joi.object({
+  id: Joi.number().integer().optional(),
+  description: Joi.when('id', {
+    is: Joi.exist(),
+    then: Joi.string().optional(),  // Optional when updating
+    otherwise: Joi.string().required()  // Required when creating
+  })
+})
+```
+
+## Best Practices
+
+1. **Always validate route parameters and outputs** - Use `schema: { input, output }` in route definition.
+2. **Strongly recommended for db functions** - Wrap all db_*() functions with schemas using `with_miolo_input_schema` or `with_miolo_output_schema`.
+3. **Use partial schemas** - Reuse common patterns from `utils/schema.mjs`
+4. **Add to partial schemas** - Extend `utils/schema.mjs` with new reusable patterns
+5. **Private + public pattern** - Use `_function_name` for implementation, export wrapped version
+6. **Default values** - Use `.default()` for optional fields with sensible defaults
+7. **Allow null carefully** - Only use `.allow(null)` when null is a valid business value
+8. **Validate early** - Validation should happen before any business logic
+9. **Remove unused properties** - `with_miolo_output_schema` ensures the client doesn't get extraneous fields.
+
+## Extending Partial Schemas
+
+Add new reusable patterns to `src/server/utils/schema.mjs`:
+
+```javascript
+// Add new partial schemas
+export const uuid = Joi.string().uuid().required()
+export const opt_uuid = Joi.string().uuid().optional()
+export const date_iso = Joi.date().iso().required()
+export const opt_date_iso = Joi.date().iso().optional()
+export const pagination = Joi.object({
+  page: Joi.number().integer().min(1).default(1),
+  limit: Joi.number().integer().min(1).max(100).default(20)
+})
+```
+
+Then use across your application:
+
+```javascript
+import { uuid, date_iso, pagination } from '#server/utils/schema.mjs'
+
+const eventSchema = Joi.object({
+  id: uuid,
+  created_at: date_iso,
+  ...pagination
+})
+```
+
+## Examples from miolo-sample
+
+See actual implementations:
+- `src/server/utils/schema.mjs` - Partial schema definitions
+- `src/server/io/db/todos/read.mjs` - Database function with schema
+- `src/server/io/db/todos/upsave.mjs` - Insert/update with schema
+- `src/server/routes/index.mjs` - Route schemas (inline and wrapper)