miolo 3.0.0-beta.204 → 3.0.0-beta.205

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miolo",
-  "version": "3.0.0-beta.204",
+  "version": "3.0.0-beta.205",
   "description": "all-in-one koa-based server",
   "author": "Donato Lorenzo <donato@afialapis.com>",
   "contributors": [

package/template/.agent/skills/miolo-app-arch/SKILL.md

@@ -5,7 +5,7 @@ description: Standard architecture patterns for miolo applications. Use when cre
 
 # Miolo Application Architecture
 
-This skill defines the standard architecture for miolo applications based on miolo-sample, the reference implementation for miolo apps.
+This skill defines the standard architecture for miolo applications, based on modern best practices (as seen in `miolo-sample`).
 
 ## Project Structure Overview
 
@@ -21,7 +21,7 @@ miolo-app/
 ├── biome.json            # Biome configuration
 ├── postcss.config.js     # PostCSS/Tailwind configuration
 ├── docker/               # Docker deployment configuration
-├── db/                   # Database initialization (optional)
+├── db/                   # Database initialization scripts and files
 ├── build/                # Production build output
 ├── src/                  # Source code
 │   ├── cli/              # Client-side React application
@@ -89,14 +89,12 @@ Docker deployment configuration:
 - `docker-compose.yaml` - Service orchestration
 - `Dockerfile` - Container build instructions
 
-### db/ (optional)
+### db/
 
 Database initialization scripts:
 - `init.sh` - Database creation and setup script
 - `sql/` - SQL migration files (executed in alphabetical order)
 
-Not required for all apps, but recommended for PostgreSQL-based applications.
-
 ### build/
 
 Production build output (generated, not versioned):
@@ -107,7 +105,7 @@ Created by `npm run build`, used in production deployment.
 
 ### src/cli/
 
-Client-side React application code. **Fixed subdirectory structure**:
+Client-side React application code. Utilizes **React Router v7** for client routing and deeply integrates **React Contexts** for state management. **Fixed subdirectory structure**:
 
 ```
 src/cli/
@@ -132,12 +130,12 @@ src/cli/
     └── ...              # Feature-specific page directories
 ```
 
-**Rules:**
+**Rules & Best Practices:**
 - Respect the subdirectory structure
-- Place new components in appropriate subdirectories
+- **React Contexts**: Contexts are heavily prioritized for global state, data caching, and UI management. 
+- **Client Routing**: Uses `react-router` v7. Main split happens in `Index.jsx` based on session state (using contexts).
 - Pages go in `pages/`, grouped by feature
 - Reusable UI components in `components/`
-- Contexts follow the established pattern (Context.jsx, Provider.jsx, useContext.mjs)
 
 ### src/ns/
 
@@ -145,55 +143,49 @@ Shared code accessible from both client and server:
 
 ```
 src/ns/
-└── models/              # Data models
-    ├── base/            # Base classes (BaseModel, BaseArray, etc.)
+└── models/              # Data models (using miolo-model)
+    ├── base/            # Base classes
     └── ...              # Application-specific models
 ```
 
-Use for code that needs to run in both environments.
+**miolo-model**: Utilize the `miolo-model` package to define robust data models that can be seamlessly validated and used across both client and server.
 
 ### src/server/
 
-Backend server code. **Semi-fixed subdirectory structure**:
+Backend server code. **Fixed subdirectory structure**:
 
 ```
 src/server/
 ├── server.mjs           # Server entry point
-├── cache/               # Cache implementations
-├── db/                  # Database layer
-│   ├── io/              # Database I/O operations (queries)
-│   │   ├── users/       # User-related queries
-│   │   ├── todos/       # Example: todo queries
-│   │   └── ...          # Feature-specific query directories
-│   └── triggers/        # Database triggers
-├── lib/                 # Server libraries
+├── bot/                 # Scripts to run from cron or console
+├── io/                  # Data I/O layer
+│   ├── cache/           # Cache layer between DB and outside world (naming: ch_)
+│   └── db/              # Database operations only. Uses schemas. (naming: db_)
+│       ├── users/       # User-related queries
+│       └── ...          # Feature-specific query directories
 ├── miolo/               # Miolo server configuration
 │   ├── auth/            # Authentication strategies
 │   ├── cache.mjs        # Cache configuration
-│   ├── cron/            # Cron jobs
 │   ├── db.mjs           # Database configuration
 │   ├── http.mjs         # HTTP configuration
 │   ├── index.mjs        # Main miolo config
 │   ├── routes/          # Base route configuration
-│   └── ssr/             # Server-side rendering
-├── routes/              # API endpoints (developers add here)
+│   └── ssr/             # Server-side rendering entry and loader
+├── routes/              # Centralized GET/POST routes. Index all r_ functions.
 │   ├── index.mjs        # Route registration
 │   ├── users/           # User endpoints
 │   └── ...              # Feature-specific route directories
+├── trigger/             # Outgoing functionalities: mailing, messaging, notifications.
 └── utils/               # Server utilities
 ```
 
 **Rules:**
-- `cache/`, `lib/`, `utils/`, `miolo/` are relatively fixed
-- **Developers add new API endpoints in `routes/`**
-- **Database queries go in `db/io/`**, organized by domain
-- Each route directory contains endpoint handlers
-- Register new routes in `routes/index.mjs`
-
-**Key pattern:** When adding a new feature:
-1. Create queries in `db/io/feature-name/`
-2. Create route handlers in `routes/feature-name/`
-3. Register routes in `routes/index.mjs`
+- **`io/db/`**: STRICTLY database operations. Functions must use validation schemas and start with `db_`.
+- **`io/cache/`**: Caching layer handling data fetching from DB with a cache mechanism. Functions start with `ch_`.
+- **`routes/`**: Centralizes all HTTP endpoints. Functions start with `r_`. These functions pick the request, and call `io/db`, `io/cache`, or `trigger/` as appropriate. Special mention applies to functions used in the `before`/`after` hooks of routes.
+- **`trigger/`**: Contains side-effect outgoing modules like emails, push notifications, or webhooks.
+- **`bot/`**: CLI or cron scripts meant to execute periodically or via the console.
+- **SSR (Server-Side Rendering)**: Configuration and loaders for SSR are stored in `miolo/ssr/`. It speeds up initial load and SEO by preloading data on the server.
 
 ### src/static/
 
@@ -203,8 +195,6 @@ Static assets:
 src/static/
 ├── fonts/               # Custom fonts
 ├── img/                 # Images
-│   ├── default/         # Default images (avatars, etc.)
-│   └── ...
 ├── public/              # Public root files (favicon, robots.txt)
 └── style/               # Global CSS
 ```
@@ -218,28 +208,6 @@ src/static/
 
 ## Best Practices
 
-1. **Respect directory structure** - Don't create new top-level directories without reason
-2. **Use import aliases** - Always use `#cli/`, `#server/`, etc. for imports
-3. **Follow naming conventions** - Use lowercase with hyphens for directories, camelCase for files
-4. **Organize by feature** - In routes/ and db/io/, group by domain/feature
-5. **Keep server config in miolo/** - Don't modify unless necessary
-6. **Use contexts for state** - Follow established context patterns in cli/context/
-
-## Common Patterns
-
-**Adding a new feature:**
-```
-1. Add database queries: src/server/db/io/myfeature/*.mjs
-2. Add API routes: src/server/routes/myfeature/*.mjs
-3. Register routes: src/server/routes/index.mjs
-4. Add client pages: src/cli/pages/myfeature/*.jsx
-5. Add components if needed: src/cli/components/myfeature/*.jsx
-```
-
-**Adding authentication:**
-- Strategies in `src/server/miolo/auth/`
-- Configure in `src/server/miolo/index.mjs`
-
 **Adding static assets:**
 - Images: `src/static/img/`
 - Fonts: `src/static/fonts/`

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

@@ -43,7 +43,7 @@ Unified authentication using Passport.js supporting both **local (username/passw
 
 ```javascript
 import { db_find_user_by_id, db_auth_user, 
-         db_user_find_or_create_from_google } from '#server/db/io/users/auth.mjs'
+         db_user_find_or_create_from_google } from '#server/io/db/users/auth.mjs'
 
 const get_user_id = (user, done, ctx) => {
   const uid = user?.id
@@ -295,7 +295,7 @@ export default [{
 
 ### User Authentication (Local)
 
-**File:** `src/server/db/io/users/auth.mjs`
+**File:** `src/server/io/db/users/auth.mjs`
 
 ```javascript
 import { sha512 } from '#server/utils/crypt.mjs'
@@ -395,7 +395,7 @@ MIOLO_SESSION_SALT=your-random-salt-here
 
 ## Database Trigger for Password Hashing
 
-**File:** `src/server/db/triggers/user.mjs`
+**File:** `src/server/io/db/triggers/user.mjs`
 
 ```javascript
 import { sha512 } from '#server/utils/crypt.mjs'
@@ -445,6 +445,6 @@ session: {
 
 See actual implementations:
 - `src/server/miolo/auth/passport.mjs` - Passport authentication config
-- `src/server/db/io/users/auth.mjs` - User authentication queries
-- `src/server/db/triggers/user.mjs` - Password hashing trigger
+- `src/server/io/db/users/auth.mjs` - User authentication queries
+- `src/server/io/db/triggers/user.mjs` - Password hashing trigger
 - `src/server/utils/crypt.mjs` - Hashing utilities

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

@@ -1,6 +1,6 @@
 ---
 name: miolo-database
-description: Database query patterns and organization for miolo applications. Use when creating database queries, organizing db/io structure, writing SQL, or implementing data access layers in miolo apps. For validation schemas, see miolo-schemas skill.
+description: Database query patterns and organization for miolo applications. Use when creating database queries, organizing io/db structure, writing SQL, or implementing data access layers in miolo apps. For validation schemas, see miolo-schemas skill.
 ---
 
 # Miolo Database Patterns
@@ -9,10 +9,10 @@ Database query organization and patterns for miolo applications using PostgreSQL
 
 ## Database Layer Organization
 
-All database queries are in `src/server/db/io/`, organized by domain:
+All database queries are in `src/server/io/db/`, organized by domain:
 
 ```
-src/server/db/io/
+src/server/io/db/
 ├── filter.mjs         # Common query filters
 ├── users/             # User-related queries
 │   ├── auth.mjs
@@ -31,7 +31,7 @@ src/server/db/io/
 All database functions follow consistent naming and structure:
 
 ```javascript
-// src/server/db/io/items/read.mjs
+// src/server/io/db/items/read.mjs
 
 export async function db_item_read(ctx, params) {
   ctx.miolo.logger.verbose('[db_item_read] Reading items...')
@@ -196,12 +196,12 @@ if (users.length === 0) {
 
 ## Query Filters with make_query_filter
 
-All SELECT queries should use `make_query_filter()` from `db/io/filter.mjs` to build WHERE clauses:
+All SELECT queries should use `make_query_filter()` from `io/db/filter.mjs` to build WHERE clauses:
 
-**File:** `src/server/db/io/filter.mjs`
+**File:** `src/server/io/db/filter.mjs`
 
 ```javascript
-import { make_query_filter } from '#server/db/io/filter.mjs'
+import { make_query_filter } from '#server/io/db/filter.mjs'
 
 export async function db_todo_read(ctx, filter) {
   ctx.miolo.logger.verbose('[db_todo_read] Reading todos...')
@@ -346,13 +346,13 @@ Run initialization:
 6. **Use transactions** - For multi-query operations that must succeed/fail together
 7. **Index properly** - Add indexes on frequently queried columns
 8. **Limit results** - Always use LIMIT for list queries to prevent large responses
-9. **Keep queries in db/io/** - Never write SQL in route handlers
+9. **Keep queries in io/db/** - Never write SQL in route handlers
 10. **Always log** - Use `ctx.miolo.logger` for all operations (`verbose` level)
 
 ## Examples from miolo-sample
 
 See actual implementations:
-- `src/server/db/io/todos/read.mjs` - Read queries
-- `src/server/db/io/todos/upsave.mjs` - Insert/update pattern
-- `src/server/db/io/users/auth.mjs` - Authentication query
+- `src/server/io/db/todos/read.mjs` - Read queries
+- `src/server/io/db/todos/upsave.mjs` - Insert/update pattern
+- `src/server/io/db/users/auth.mjs` - Authentication query
 - `src/server/miolo/db.mjs` - Database configuration

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

@@ -5,7 +5,7 @@ description: API routing patterns for miolo applications. Use when creating or m
 
 # Miolo Routing Patterns
 
-Standard patterns for creating API routes in miolo applications following miolo-sample conventions.
+Standard patterns for creating API routes in miolo applications following miolo conventions.
 
 ## Route Organization
 
@@ -61,7 +61,7 @@ export default [{
 Route handlers receive `(ctx, params)` and return `{ ok, data }` or `{ ok, error }`:
 
 ```javascript
-import { db_item_read } from '#server/db/io/items/read.mjs'
+import { db_item_read } from '#server/io/db/items/read.mjs'
 
 export async function r_item_list(ctx, params) {
   try {
@@ -114,8 +114,8 @@ Complete CRUD implementation:
 
 ```javascript
 // items/mod.mjs
-import { db_item_upsave } from '#server/db/io/items/upsave.mjs'
-import { db_item_delete } from '#server/db/io/items/delete.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 {
@@ -280,9 +280,9 @@ export async function r_item_find(ctx, params) {
 
 ## Adding a New Feature
 
-1. **Create database functions** in `src/server/db/io/feature/`:
+1. **Create database functions** in `src/server/io/db/feature/`:
    ```javascript
-   // db/io/items/read.mjs
+   // io/db/items/read.mjs
    export async function db_item_read(ctx, params) { /* ... */ }
    ```
 
@@ -308,14 +308,14 @@ export async function r_item_find(ctx, params) {
 
 ## Best Practices
 
-1. **Use database abstraction** - Never write SQL in routes, use `db/io/` functions
+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 `db/io/`, routes only handle HTTP
+8. **Keep handlers thin** - Business logic in `io/db/`, routes only handle HTTP
 
 ## Examples from miolo-sample
 

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

@@ -324,6 +324,6 @@ const eventSchema = Joi.object({
 
 See actual implementations:
 - `src/server/utils/schema.mjs` - Partial schema definitions
-- `src/server/db/io/todos/read.mjs` - Database function with schema
-- `src/server/db/io/todos/upsave.mjs` - Insert/update with schema
+- `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)

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

@@ -16,8 +16,8 @@ The SSR loader preloads data on the server before sending the initial HTML to th
 **File:** `src/server/miolo/ssr/loader.mjs`
 
 ```javascript
-import { db_todo_read } from '#server/db/io/todos/read.mjs'
-import { db_user_profile } from '#server/db/io/users/read.mjs'
+import { db_todo_read } from '#server/io/db/todos/read.mjs'
+import { db_user_profile } from '#server/io/db/users/read.mjs'
 
 const loader = async (ctx) => {
   let todos = []

package/template/package.json

@@ -13,7 +13,7 @@
     "deb": "npx miolo deb",
     "create-bin": "npx miolo create-bin",
     "build": "rm -fr build/cli/* build/server/* &&npx miolo build && npm run create-bin",
-    "build-bin": "npx miolo build-bin --bin-entry=src/server/console/check_today.mjs",
+    "build-bin": "npx miolo build-bin --bin-entry=src/server/bot/check_today.mjs",
     "start": "node ./build/server/run.mjs start 1>> /var/log/miolo-sample.log 2>&1",
     "stop": "node ./build/server/run.mjs stop 1>> /var/log/miolo-sample.log 2>&1",
     "restart": "node ./build/server/run.mjs restart 1>> /var/log/miolo-sample.log 2>&1"
@@ -45,9 +45,9 @@
     "intre": "^3.0.0-beta.4",
     "joi": "^18.2.1",
     "lucide-react": "^1.16.0",
-    "miolo-cli": "^3.0.0-beta.204",
+    "miolo-cli": "^3.0.0-beta.205",
     "miolo-model": "file:../miolo-model",
-    "miolo-react": "^3.0.0-beta.204",
+    "miolo-react": "^3.0.0-beta.205",
     "next-themes": "^0.4.6",
     "radix-ui": "^1.4.3",
     "react": "^19.2.6",
@@ -62,7 +62,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
-    "miolo": "^3.0.0-beta.204",
+    "miolo": "^3.0.0-beta.205",
     "sass-embedded": "^1.100.0"
   },
   "overrides": {

package/template/src/server/{db/io → io/db}/todos/read.mjs

@@ -1,6 +1,6 @@
 import Joi from "joi"
 import { with_miolo_input_schema } from "miolo"
-import { make_query_filter } from "#server/db/io/filter.mjs"
+import { make_query_filter } from "#server/io/db/filter.mjs"
 import { bool_null, opt_int, opt_str_null } from "#server/utils/schema.mjs"
 
 /**

package/template/src/server/miolo/auth/basic.mjs

@@ -1,4 +1,4 @@
-import { db_auth_user } from "#server/db/io/users/auth.mjs"
+import { db_auth_user } from "#server/io/db/users/auth.mjs"
 
 const local_auth_user = async (username, password, ctx) => {
   const [user, msg] = await db_auth_user(ctx.miolo, username, password)

package/template/src/server/miolo/auth/passport.mjs

@@ -2,7 +2,7 @@ import {
   db_auth_user,
   db_find_user_by_id,
   db_user_find_or_create_from_google
-} from "#server/db/io/users/auth.mjs"
+} from "#server/io/db/users/auth.mjs"
 
 const get_user_id = async (user, ctx) => {
   ctx.miolo.logger.debug(

package/template/src/server/miolo/db.mjs

@@ -1,6 +1,6 @@
 // import path from 'path'
 // import {fileURLToPath} from 'url'
-import { beforeInsertUser } from "#server/db/triggers/user.mjs"
+import { beforeInsertUser } from "#server/io/db/triggers/user.mjs"
 
 // const __filename = fileURLToPath(import.meta.url)
 // const __dirname = path.dirname(__filename)

package/template/src/server/miolo/ssr/loader.mjs

@@ -1,4 +1,4 @@
-import { db_todo_read } from "#server/db/io/todos/read.mjs"
+import { db_todo_read } from "#server/io/db/todos/read.mjs"
 
 const loader = async (ctx) => {
   let lastTodos = []

package/template/src/server/routes/todos/mod.mjs

@@ -1,6 +1,6 @@
-import { db_todo_delete } from "#server/db/io/todos/delete.mjs"
-import { db_todo_toggle } from "#server/db/io/todos/toggle.mjs"
-import { db_todo_upsave } from "#server/db/io/todos/upsave.mjs"
+import { db_todo_delete } from "#server/io/db/todos/delete.mjs"
+import { db_todo_toggle } from "#server/io/db/todos/toggle.mjs"
+import { db_todo_upsave } from "#server/io/db/todos/upsave.mjs"
 
 export async function r_todo_upsave(ctx, params) {
   try {

package/template/src/server/routes/todos/read.mjs

@@ -1,5 +1,5 @@
-import { db_todo_find } from "#server/db/io/todos/find.mjs"
-import { db_todo_read } from "#server/db/io/todos/read.mjs"
+import { db_todo_find } from "#server/io/db/todos/find.mjs"
+import { db_todo_read } from "#server/io/db/todos/read.mjs"
 
 export async function r_todo_list(ctx, _params) {
   try {

package/template/src/server/routes/users/user.mjs

@@ -1,5 +1,5 @@
-import { db_password_change } from "#server/db/io/users/pwd.mjs"
-import { db_user_save } from "#server/db/io/users/save.mjs"
+import { db_password_change } from "#server/io/db/users/pwd.mjs"
+import { db_user_save } from "#server/io/db/users/save.mjs"
 import { generateRandomPassword } from "#server/utils/crypt.mjs"
 
 export async function r_forgot(ctx, params) {