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

package/src/middleware/vite/devserver.mjs

@@ -1,42 +1,58 @@
-
-import koaConnect from 'koa-connect'
+import tailwindVite from "@tailwindcss/vite"
+import react from "@vitejs/plugin-react"
+import koaConnect from "koa-connect"
+// import { resolve } from 'path'
+import { createServer } from "vite"
 
 // Vite Dev Server
 export async function init_vite_dev_server_middleware(app, viteConfig) {
-  const isProduction = process.env.NODE_ENV === 'production'
+  const isProduction = process.env.NODE_ENV === "production"
   let vite
 
   if (!isProduction) {
-    const { createServer } = await import('vite')
-    const react = await import('@vitejs/plugin-react')
+    // const tailwindConfigPath = resolve(process.cwd(), 'tailwind.config.js')
+    // const tailwindConfig = await import(tailwindConfigPath)
+
+    const serverConfig = viteConfig?.server || {}
+    delete viteConfig?.server
 
     vite = await createServer({
-      server: { middlewareMode: true },
-      appType: 'custom',
-      plugins: [react.default(
-        {
+      server: {
+        middlewareMode: true,
+        port: process.env?.MIOLO_PORT || 8001,
+        hmr: {
+          port: process.env?.MIOLO_DEV_PORT || (process.env?.MIOLO_PORT || 8001) - 1000
+        },
+
+        ...serverConfig
+      },
+      appType: "custom",
+      plugins: [
+        react({
           babel: {
-            plugins: [
-              ["@babel/plugin-proposal-decorators", { "legacy": true }]
-            ]
+            plugins: [["@babel/plugin-proposal-decorators", { legacy: true }]]
           }
-        }
-      )],
-      ...viteConfig || {},
-      // 
-      base: viteConfig?.base || '/',
-      root: viteConfig?.root || '',
+        }),
+        tailwindVite(
+          // @tailwindcss/vite does not accept params
+          //{config: tailwindConfig}
+        )
+      ],
+      ...(viteConfig || {}),
+      //
+      base: viteConfig?.base || "/",
+      root: viteConfig?.root || process.cwd(),
       watch: {
         // During tests we edit the files too fast and sometimes chokidar
         // misses change events, so enforce polling for consistency
         usePolling: true,
         interval: 100,
-        ...viteConfig?.vite?.watch || {}
+        ...(viteConfig?.vite?.watch || {})
       }
     })
 
     app.use(koaConnect(vite.middlewares))
-  } 
+  }
 
-  app.vite= vite
-}
+  app.vite = vite
+}

package/src/middleware/vite/watcher.mjs

@@ -1,29 +1,27 @@
-import path from 'path'
-
+import path from "node:path"
 
 // Resuse Vite Watcher
-export async function init_watcher_dev_server_middleware(app, watcherConfig, ssrConfig) {
+export async function init_watcher_dev_server_middleware(app, watcherConfig, _ssrConfig) {
   let watcher
 
   const isEnabled = watcherConfig?.enabled === true
-  const isProduction = process.env.NODE_ENV === 'production'
-  
-  if (isEnabled && (!isProduction)){
+  const isProduction = process.env.NODE_ENV === "production"
 
-    // Let's reuse Vite's cholkidar instance to listen to changes in server code
+  if (isEnabled && !isProduction) {
+    // Let's reuse Vite's chokidar instance to listen to changes in server code
     watcher = app.vite.watcher
 
     // Extra dirs to watch
-    const serverDirsToWatch = watcherConfig?.dirs || ['server', 'src/server']
+    const serverDirsToWatch = watcherConfig?.dirs || ["server", "src/server"]
 
     // Listen to changes in the extra dirs
     serverDirsToWatch.forEach((dir) => {
       watcher.add(path.resolve(process.cwd(), dir))
       app.context.miolo.logger.info(`[watcher] Vite is now watching for changes also in: ${dir}`)
     })
-   
+
     // Listen to changes in the extra dirs
-    watcher.on('change', async (filePath) => {
+    watcher.on("change", async (filePath) => {
       let isCustom = false
       serverDirsToWatch.forEach((dir) => {
         if (filePath.startsWith(path.resolve(process.cwd(), dir))) {
@@ -34,9 +32,9 @@ export async function init_watcher_dev_server_middleware(app, watcherConfig, ssr
       app.context.miolo.logger.info(`[watcher] File changed: ${filePath}. Reloading server...`)
 
       await app.stop()
-      process.send('miolo_restart') // Envía un mensaje al proceso padre para reiniciar
+      process.send("miolo_restart") // Envía un mensaje al proceso padre para reiniciar
     })
-  } 
+  }
 
-  app.watcher= watcher
-}
+  app.watcher = watcher
+}

package/src/server-cron.mjs

@@ -1,9 +1,9 @@
-import { init_config }                     from './config/index.mjs'
-import { init_context_middleware }         from './middleware/context/index.mjs'
-import { init_cron }                       from './engines/cron/index.mjs'
+import { init_config } from "./config/index.mjs"
+import { init_cron } from "./engines/cron/index.mjs"
+import { init_socket } from "./engines/socket/index.mjs"
+import { init_context_middleware } from "./middleware/context/index.mjs"
 
 export async function miolo_cron(makeConfig) {
-
   const app = {
     use: () => {},
     context: {}
@@ -11,21 +11,23 @@ export async function miolo_cron(makeConfig) {
 
   // Init some pieces
   const config = init_config(makeConfig)
-  
+
   // attach to app some custom miolo methods
   init_context_middleware(app, config)
 
-
   // Init cron (will not start jobs yet)
   init_cron(app, config?.cron)
-    
+
   // Util callbacks
   app.start = async () => {
     // Init and reset db connection
     await app.context.miolo.db.init_connection()
+    if (app.context.miolo?.io) {
+      app.context.miolo.io.attach(app.http.server)
+    }
     await app.cron.start()
   }
-  
+
   app.stop = async () => {
     await app.context.miolo.db.drop_connections()
     await app.cron.stop()
@@ -36,5 +38,8 @@ export async function miolo_cron(makeConfig) {
     await app.start()
   }
 
+  // Socket.io
+  init_socket(app, config?.socket)
+
   return app
 }

package/src/server-dev.mjs

@@ -1,43 +1,40 @@
+import { init_vite_dev_server_middleware } from "./middleware/vite/devserver.mjs"
+import { init_watcher_dev_server_middleware } from "./middleware/vite/watcher.mjs"
 import { miolo } from "./server.mjs"
-import { init_vite_dev_server_middleware } from './middleware/vite/devserver.mjs'
-import { init_watcher_dev_server_middleware } from './middleware/vite/watcher.mjs'
 
 /**
- * We use two separated servers 
+ * We use two separated servers
  *   coz VITE code causes bundle errors when bundling
- *   for production, and plugin-replace seems not enough 
+ *   for production, and plugin-replace seems not enough
  *   to remove the Vite dev-unused code.
- * 
- * So we need to neither 'import' nor 'await import' 
+ *
+ * So we need to neither 'import' nor 'await import'
  *   Vite code at all on the Prod server.
- * 
- * miolo_dev() will be available thourgh a different 
+ *
+ * miolo_dev() will be available thourgh a different
  *   package import (miolo/server-dev)
  */
 export async function miolo_dev(makeConfig) {
-  
   // Vite DEV server init
-  const devInit= async (app, config) => {
+  const devInit = async (app, config) => {
     await init_vite_dev_server_middleware(app, config.build.vite)
     await init_watcher_dev_server_middleware(app, config.build.dev.watcher, config.build.ssr)
   }
 
   // Vite SSR side
-  const devRender= async (app, ctx, base_html, ssrConfig) => {
+  const devRender = async (app, ctx, base_html, ssrConfig) => {
     try {
-      const url = ctx.request.originalUrl.replace(app.vite.config.base || '/', '')
+      const url = ctx.request.originalUrl.replace(app.vite.config.base || "/", "")
       const html = await app.vite.transformIndexHtml(url, base_html)
       const render = (await app.vite.ssrLoadModule(ssrConfig.server)).render
       return [html, render]
-    } catch(error) {
+    } catch (error) {
       app.vite?.ssrFixStacktrace(error)
       ctx.miolo.logger.error(`SSR Error (Vite mode):\n${error.toString()}`)
       ctx.miolo.logger.error(error.stack)
       return [undefined, undefined]
     }
   }
-  
+
   return await miolo(makeConfig, devInit, devRender)
 }
-
-

package/src/server.mjs

@@ -1,33 +1,25 @@
-import Koa                                from 'koa'
-import { init_config }                    from './config/index.mjs'
-
-import { init_context_middleware }         from './middleware/context/index.mjs'
-// import { init_vite_dev_server_middleware } from './middleware/vite/devserver.mjs'
-import { init_headers_middleware }         from './middleware/http/headers.mjs'
-import { init_body_middleware }            from './middleware/http/body.mjs'
-import { init_catcher_middleware }         from './middleware/http/catcher.mjs'
-import { init_rate_limit_middleware }      from './middleware/http/ratelimit.mjs'
-import { init_static_middleware }          from './middleware/static/index.mjs'
-import { init_request_middleware }         from './middleware/http/request.mjs'
-import { init_route_robots }               from './middleware/routes/robots.mjs'
-import { init_route_catch_js_error}        from './middleware/routes/catch_js_error.mjs'
-
-import {init_guest_auth_middleware}        from'./middleware/auth/guest.mjs'
-import {init_basic_auth_middleware}        from'./middleware/auth/basic.mjs'
-import {init_credentials_auth_middleware}  from'./middleware/auth/credentials/index.mjs'
-import {init_custom_auth_middleware}       from'./middleware/auth/custom.mjs'
-
-import { init_extra_middlewares }          from './middleware/extra.mjs'
-import { init_router }                     from './middleware/routes/router/index.mjs'
-
-import { init_ssr_render_middleware }      from './middleware/ssr/ssr_render.mjs'
-
-//import {init_socket}                      from './engines/socket/index.mjs'
-import { init_cron }                       from './engines/cron/index.mjs'
-import { init_http_server }                from './engines/http/index.mjs'
-
-async function miolo(makeConfig, devInit= undefined, devRender= undefined) {
-
+import Koa from "koa"
+import { init_config } from "./config/index.mjs"
+import { init_cron } from "./engines/cron/index.mjs"
+import { init_http_server } from "./engines/http/index.mjs"
+import { init_socket } from "./engines/socket/index.mjs"
+import { init_basic_auth_middleware } from "./middleware/auth/basic.mjs"
+import { init_guest_auth_middleware } from "./middleware/auth/guest.mjs"
+import { init_passport_auth_middleware } from "./middleware/auth/passport/index.mjs"
+import { init_context_middleware } from "./middleware/context/index.mjs"
+import { init_extra_middlewares } from "./middleware/extra.mjs"
+import { init_body_middleware } from "./middleware/http/body.mjs"
+import { init_catcher_middleware } from "./middleware/http/catcher.mjs"
+import { init_headers_middleware } from "./middleware/http/headers.mjs"
+import { init_rate_limit_middleware } from "./middleware/http/ratelimit.mjs"
+import { init_request_middleware } from "./middleware/http/request.mjs"
+import { init_route_catch_js_error } from "./middleware/routes/catch_js_error.mjs"
+import { init_route_robots } from "./middleware/routes/robots.mjs"
+import { init_router } from "./middleware/routes/router/index.mjs"
+import { init_ssr_render_middleware } from "./middleware/ssr/ssr_render.mjs"
+import { init_static_middleware } from "./middleware/static/index.mjs"
+
+async function miolo(makeConfig, devInit = undefined, devRender = undefined) {
   const app = new Koa()
 
   // Init some pieces
@@ -39,12 +31,11 @@ async function miolo(makeConfig, devInit= undefined, devRender= undefined) {
   // Vite Dev Server
   if (devInit) {
     await devInit(app, config)
-    // await init_vite_dev_server_middleware(app, config.build.vite)
   }
-  
+
   // CORS and other headers
-  init_headers_middleware(app, config.http)    
-  
+  init_headers_middleware(app, config.http)
+
   // Compress and body parser
   init_body_middleware(app)
 
@@ -69,24 +60,20 @@ async function miolo(makeConfig, devInit= undefined, devRender= undefined) {
   }
 
   // auth middleware
-  if (config.auth_type == 'guest') {
+  if (config.auth.guest.enabled === true) {
     init_guest_auth_middleware(app, config.auth.guest, config?.session)
-  }  
-
-  if (config.auth_type == 'basic') {
-    init_basic_auth_middleware(app, config.auth.basic)
   }
 
-  if (config.auth_type == 'credentials') {
-    init_credentials_auth_middleware(app, config.auth.credentials, config?.session, config?.cache)
+  if (config.auth.basic.enabled === true) {
+    init_basic_auth_middleware(app, config.auth.basic)
   }
 
-  if (config.auth_type == 'custom') {
-    init_custom_auth_middleware(app, config.auth.custom)
+  if (config.auth.passport.enabled === true) {
+    init_passport_auth_middleware(app, config.auth.passport, config?.session, config?.cache)
   }
 
   // extra middlewares
-  const extra_middlewares= config?.middlewares
+  const extra_middlewares = config?.middlewares
   if (extra_middlewares) {
     init_extra_middlewares(app, extra_middlewares)
   }
@@ -101,21 +88,32 @@ async function miolo(makeConfig, devInit= undefined, devRender= undefined) {
 
   // Init cron (will not start jobs yet)
   init_cron(app, config?.cron)
-    
+
   // Init http server
-  init_http_server(app, config?.http) 
+  init_http_server(app, config?.http)
 
   // Util callbacks
   app.start = async () => {
     // Init and reset db connection
     await app.context.miolo.db.init_connection()
-    
+    await app.context.miolo.cache.init()
+    if (app?.initSessionStore) {
+      await app.initSessionStore()
+    }
+
     await app.http.start()
+    if (app.context.miolo?.io) {
+      app.context.miolo.io.attach(app.http.server)
+    }
     await app.cron.start()
   }
-  
+
   app.stop = async () => {
     await app.context.miolo.db.drop_connections()
+    await app.context.miolo.cache.close()
+    if (app?.closeSessionStore) {
+      await app.closeSessionStore()
+    }
     await app.http.stop()
     await app.cron.stop()
     if (app?.vite) {
@@ -126,12 +124,12 @@ async function miolo(makeConfig, devInit= undefined, devRender= undefined) {
   app.restart = async () => {
     await app.stop()
     await app.start()
-  }  
+  }
 
   // Socket.io
-  // init_socket(app, config?.socket)
+  init_socket(app, config?.socket)
 
   return app
 }
 
-export {miolo}
+export { miolo }

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

@@ -0,0 +1,218 @@
+---
+name: miolo-app-arch
+description: Standard architecture patterns for miolo applications. Use when creating, modifying, or reviewing miolo applications to ensure proper project structure, directory organization, and file placement following miolo conventions established in miolo-sample.
+---
+
+# Miolo Application Architecture
+
+This skill defines the standard architecture for miolo applications, based on modern best practices (as seen in `miolo-sample`).
+
+## Project Structure Overview
+
+```
+miolo-app/
+├── package.json          # npm scripts and dependencies
+├── .env                  # Development environment variables
+├── .env.production       # Production environment variables  
+├── .editorconfig         # Editor configuration
+├── .gitignore            # Git ignore rules
+├── components.json       # shadcn/ui configuration
+├── jsconfig.json         # JavaScript/Import path configuration
+├── biome.json            # Biome configuration
+├── postcss.config.js     # PostCSS/Tailwind configuration
+├── docker/               # Docker deployment configuration
+├── db/                   # Database initialization scripts and files
+├── build/                # Production build output
+├── src/                  # Source code
+│   ├── cli/              # Client-side React application
+│   ├── ns/               # Shared code (namespace)
+│   ├── server/           # Backend server code
+│   └── static/           # Static assets
+```
+
+## Root Files
+
+### package.json Scripts
+
+Standard npm scripts for miolo development and deployment:
+
+```json
+{
+  "scripts": {
+    "reset": "rm -fr node_modules package-lock.json && npm i",
+    "lint": "biome check ./src --reporter=github",
+    "lint:fix": "biome check --write ./src --reporter=github",
+    "dev": "npx miolo dev",
+    "deb": "npx miolo deb",
+    "create-bin": "npx miolo create-bin",
+    "build": "npx miolo build && npm run create-bin",
+    "start": "node ./build/server/run.mjs start",
+    "stop": "node ./build/server/run.mjs stop",
+    "restart": "node ./build/server/run.mjs restart"
+  }
+}
+```
+
+**Key scripts:**
+- `dev` - Development mode with hot reload
+- `deb` - Development mode with hot reload and debugging
+- `build` - Complete production build
+- `start/stop/restart` - Production server management
+
+### Import Aliases
+
+Configure path aliases in `package.json`:
+
+```json
+{
+  "imports": {
+    "#cli/*": "./src/cli/*",
+    "#ns/*": "./src/ns/*",
+    "#server/*": "./src/server/*",
+    "#static/*": "./src/static/*"
+  }
+}
+```
+
+Use these aliases consistently in imports: `import Thing from '#server/routes/thing.mjs'`
+
+### Environment Files
+
+- `.env` - Development configuration (database, ports, session salt, etc.)
+- `.env.production` - Production overrides
+
+## Directory Structure
+
+### docker/
+
+Docker deployment configuration:
+- `docker-compose.yaml` - Service orchestration
+- `Dockerfile` - Container build instructions
+
+### db/
+
+Database initialization scripts:
+- `init.sh` - Database creation and setup script
+- `sql/` - SQL migration files (executed in alphabetical order)
+
+### build/
+
+Production build output (generated, not versioned):
+- `cli/` - Built client application
+- `server/` - Built server application
+
+Created by `npm run build`, used in production deployment.
+
+### src/cli/
+
+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/
+├── App.jsx              # Root application component
+├── entry-cli.jsx        # Client entry point
+├── index.html           # HTML template
+├── components/          # React components (shadcn/ui, custom)
+│   ├── ui/              # shadcn/ui components
+│   └── ...              # Custom components
+├── config/              # Client configuration
+├── context/             # React contexts (data, session, theme, ui)
+│   ├── data/
+│   ├── session/
+│   ├── theme/
+│   └── ui/
+├── hooks/               # Custom React hooks
+├── layout/              # Layout components (sidebar, nav, etc.)
+├── lib/                 # Client utilities
+└── pages/               # Page components
+    ├── dash/            # Dashboard pages
+    ├── offline/         # Unauthenticated pages (login, etc.)
+    └── ...              # Feature-specific page directories
+```
+
+**Rules & Best Practices:**
+- Respect the subdirectory structure
+- **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/`
+
+### src/ns/
+
+Shared code accessible from both client and server:
+
+```
+src/ns/
+└── models/              # Data models (using miolo-model)
+    ├── base/            # Base classes
+    └── ...              # Application-specific models
+```
+
+**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. **Fixed subdirectory structure**:
+
+```
+src/server/
+├── server.mjs           # Server entry point
+├── 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
+│   ├── db.mjs           # Database configuration
+│   ├── http.mjs         # HTTP configuration
+│   ├── index.mjs        # Main miolo config
+│   ├── routes/          # Base route configuration
+│   └── 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:**
+- **`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/
+
+Static assets:
+
+```
+src/static/
+├── fonts/               # Custom fonts
+├── img/                 # Images
+├── public/              # Public root files (favicon, robots.txt)
+└── style/               # Global CSS
+```
+
+## Development Workflow
+
+1. **Create app**: `npx miolo create <app-name>`
+2. **Develop**: `npm run dev` (hot reload on port from .env)
+3. **Build**: `npm run build` (creates production build/)
+4. **Deploy**: Use docker/ configuration or build/server/run.mjs
+
+## Best Practices
+
+**Adding static assets:**
+- Images: `src/static/img/`
+- Fonts: `src/static/fonts/`
+- Root files: `src/static/public/`
+
+## Architecture created by `npx miolo create`
+
+The `miolo create` command generates this structure automatically. Maintain it throughout development to ensure consistency with miolo conventions and compatibility with miolo tooling.