miolo 3.0.0-beta.152 → 3.0.0-beta.154

package/bin/create/copy.mjs

@@ -153,8 +153,8 @@ export function copyTemplate(sourcePath, destPath, appName, options = {}) {
         fs.copyFileSync(srcPath, destItemPath)
       }
     } else if (stat.isDirectory()) {
-      // Only copy src/, db/ and docker/ directories
-      if (item === 'src' || item === 'docker'|| item === 'db') {
+      // Copy src/, db/, docker/, and .agent/ directories
+      if (item === 'src' || item === 'docker' || item === 'db' || item === '.agent') {
         copyDirectory(srcPath, destItemPath, appName, options)
       }
     }

package/bin/create/prepare-template.mjs

@@ -74,6 +74,17 @@ for (const dir of dirsToCopy) {
   }
 }
 
+// Copy skills from workspace root
+const skillsSrc = path.resolve(__dirname, '../../../../skills')
+const skillsDest = path.join(templatePath, '.agent', 'skills')
+if (fs.existsSync(skillsSrc)) {
+  fs.mkdirSync(path.join(templatePath, '.agent'), { recursive: true })
+  copyDirRecursive(skillsSrc, skillsDest)
+  console.log('[prepare-template]   ✓ Copied skills/')
+} else {
+  console.warn('[prepare-template]   ⚠ Skills directory not found at', skillsSrc)
+}
+
 // Step 4: Update package.json versions
 console.log('[prepare-template] Updating package.json versions...')
 const templatePackageJsonPath = path.join(templatePath, 'package.json')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miolo",
-  "version": "3.0.0-beta.152",
+  "version": "3.0.0-beta.154",
   "description": "all-in-one koa-based server",
   "author": "Donato Lorenzo <donato@afialapis.com>",
   "contributors": [
@@ -30,7 +30,8 @@
     "template",
     "template/.env",
     "template/.env.production",
-    "template/.editorconfig"
+    "template/.editorconfig",
+    "template/.agent"
   ],
   "scripts": {
     "lint": "npx xeira lint ./src",

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

@@ -0,0 +1,251 @@
+---
+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 miolo-sample, the reference implementation for miolo apps.
+
+## 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
+├── eslint.config.js      # ESLint configuration
+├── postcss.config.js     # PostCSS/Tailwind configuration
+├── docker/               # Docker deployment configuration
+├── db/                   # Database initialization (optional)
+├── 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": "npx xeira lint src",
+    "dev": "npx miolo dev",
+    "deb": "npx miolo deb",
+    "create-bin": "npx miolo create-bin",
+    "build-client": "npx miolo build-client",
+    "build-server": "npx miolo build-server",
+    "build": "npm run build-client && npm run build-server && 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/ (optional)
+
+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):
+- `cli/` - Built client application
+- `server/` - Built server application
+
+Created by `npm run build`, used in production deployment.
+
+### src/cli/
+
+Client-side React application code. **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:**
+- Respect the subdirectory structure
+- Place new components in appropriate subdirectories
+- 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/
+
+Shared code accessible from both client and server:
+
+```
+src/ns/
+└── models/              # Data models
+    ├── base/            # Base classes (BaseModel, BaseArray, etc.)
+    └── ...              # Application-specific models
+```
+
+Use for code that needs to run in both environments.
+
+### src/server/
+
+Backend server code. **Semi-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
+├── 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)
+│   ├── index.mjs        # Route registration
+│   ├── users/           # User endpoints
+│   └── ...              # Feature-specific route directories
+└── 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`
+
+### src/static/
+
+Static assets:
+
+```
+src/static/
+├── fonts/               # Custom fonts
+├── img/                 # Images
+│   ├── default/         # Default images (avatars, etc.)
+│   └── ...
+├── 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
+
+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/`
+- 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.

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

@@ -0,0 +1,295 @@
+---
+name: miolo-auth
+description: Authentication configuration and strategies for miolo applications. Use when implementing, modifying, or troubleshooting authentication, configuring auth strategies (credentials, basic, guest), or setting up user sessions.
+---
+
+# Miolo Authentication
+
+Authentication configuration and strategies for miolo applications.
+
+## Authentication Strategies
+
+Miolo supports multiple built-in authentication strategies in `src/server/miolo/auth/`:
+
+```
+src/server/miolo/auth/
+├── credentials.mjs    # Username/password authentication
+├── basic.mjs          # HTTP Basic authentication
+├── guest.mjs          # Guest/anonymous access
+└── custom.mjs         # Custom authentication logic
+```
+
+## Configuring Authentication
+
+Authentication is configured in `src/server/miolo/index.mjs`:
+
+```javascript
+import auth from './auth/credentials.mjs'
+// or: import auth from './auth/basic.mjs'
+// or: import auth from './auth/guest.mjs'
+
+export default {
+  auth,
+  // ... other config
+}
+```
+
+## Credentials Strategy (Default)
+
+Username/password authentication with database-backed users.
+
+**File:** `src/server/miolo/auth/credentials.mjs`
+
+```javascript
+import { db_user_auth } from '#server/db/io/users/auth.mjs'
+
+export default {
+  urls: {
+    login: '/page/login',
+    logout: '/page/logout',
+    home: '/'
+  },
+
+  async login(ctx, credentials) {
+    const { username, password } = credentials
+    
+    const user = await db_user_auth(ctx, { username, password })
+    
+    if (!user) {
+      return { ok: false, error: 'Invalid credentials' }
+    }
+    
+    return { ok: true, user }
+  },
+
+  async logout(ctx) {
+    // Cleanup if needed
+    return { ok: true }
+  }
+}
+```
+
+**Key elements:**
+- `urls` - Define login, logout, home page paths
+- `login(ctx, credentials)` - Validates credentials, returns user or error
+- `logout(ctx)` - Optional cleanup on logout
+- Uses database function from `db/io/users/auth.mjs`
+
+## Basic Authentication
+
+HTTP Basic Auth for simple API access.
+
+**File:** `src/server/miolo/auth/basic.mjs`
+
+```javascript
+export default {
+  async login(ctx, credentials) {
+    const { username, password } = credentials
+    
+    // Validate against environment or database
+    if (username === process.env.API_USER && 
+        password === process.env.API_PASSWORD) {
+      return {
+        ok: true,
+        user: { id: 1, username, role: 'api' }
+      }
+    }
+    
+    return { ok: false, error: 'Invalid credentials' }
+  }
+}
+```
+
+## Guest/Anonymous Access
+
+Allow unauthenticated access (useful for read-only apps).
+
+**File:** `src/server/miolo/auth/guest.mjs`
+
+```javascript
+export default {
+  async login(ctx) {
+    return {
+      ok: true,
+      user: { id: 0, username: 'guest', role: 'guest' }
+    }
+  }
+}
+```
+
+## User Session
+
+After successful login, user is available in routes:
+
+```javascript
+export async function r_protected_route(ctx, params) {
+  const user = ctx.state.user
+  
+  // User object contains:
+  // - id
+  // - username
+  // - email
+  // - any other fields returned from login
+  
+  ctx.miolo.logger.info(`User ${user.id} accessing route`)
+  
+  return { ok: true, data: { userId: user.id } }
+}
+```
+
+## Protecting Routes
+
+Routes are protected by adding `auth` configuration:
+
+```javascript
+const auth = {
+  require: true,
+  action: 'redirect',
+  redirect_url: '/page/login'
+}
+
+export default [{
+  prefix: 'api',
+  routes: [
+    // Public route
+    { method: 'GET', url: '/public/data', callback: r_public },
+    
+    // Protected route
+    { method: 'GET', url: '/user/profile', auth, callback: r_profile },
+  ]
+}]
+```
+
+## Database User Authentication
+
+User authentication typically queries the database:
+
+**File:** `src/server/db/io/users/auth.mjs`
+
+```javascript
+import { sha512 } from '#server/utils/crypt.mjs'
+
+export async function db_user_auth(ctx, params) {
+  const { username, password } = params
+  
+  const salt = process.env.MIOLO_SESSION_SALT
+  const hashedPassword = sha512(password, salt)
+  
+  const user = await ctx.miolo.db.query(`
+    SELECT id, username, email, name
+    FROM u_user
+    WHERE username = $1 AND password = $2
+  `, [username, hashedPassword])
+  
+  return user.rows[0] || null
+}
+```
+
+**Key elements:**
+- Hash password with session salt
+- Query user by username and hashed password
+- Return user object or null
+- Don't return password in user object
+
+## Password Hashing
+
+Use the provided crypto utilities:
+
+```javascript
+import { sha512 } from '#server/utils/crypt.mjs'
+
+const salt = process.env.MIOLO_SESSION_SALT
+const hashedPassword = sha512(plainPassword, salt)
+```
+
+**Session salt** is configured in `.env`:
+```
+MIOLO_SESSION_SALT=your-random-salt-here
+```
+
+## Changing Password
+
+Pattern for password change:
+
+**File:** `src/server/db/io/users/pwd.mjs`
+
+```javascript
+import { sha512 } from '#server/utils/crypt.mjs'
+
+export async function db_user_change_password(ctx, params) {
+  const { user_id, old_password, new_password } = params
+  
+  const salt = process.env.MIOLO_SESSION_SALT
+  
+  // Verify old password
+  const user = await ctx.miolo.db.query(`
+    SELECT id FROM u_user
+    WHERE id = $1 AND password = $2
+  `, [user_id, sha512(old_password, salt)])
+  
+  if (user.rows.length === 0) {
+    throw new Error('Invalid current password')
+  }
+  
+  // Update to new password
+  const newHash = sha512(new_password, salt)
+  await ctx.miolo.db.query(`
+    UPDATE u_user
+    SET password = $1
+    WHERE id = $2
+  `, [newHash, user_id])
+
+  return { changed: true }
+}
+```
+
+## Custom Authentication
+
+For complex scenarios, implement custom logic:
+
+**File:** `src/server/miolo/auth/custom.mjs`
+
+```javascript
+export default {
+  urls: {
+    login: '/auth/custom',
+    logout: '/auth/logout',
+    home: '/'
+  },
+
+  async login(ctx, credentials) {
+    // Custom logic: OAuth, LDAP, etc.
+    const user = await yourCustomAuthLogic(credentials)
+    
+    if (!user) {
+      return { ok: false, error: 'Authentication failed' }
+    }
+    
+    return { ok: true, user }
+  },
+
+  async logout(ctx) {
+    // Custom cleanup
+    await yourCustomLogoutLogic(ctx)
+    return { ok: true }
+  }
+}
+```
+
+## Best Practices
+
+1. **Never store plain passwords** - Always hash with salt
+2. **Use strong session salt** - Set `MIOLO_SESSION_SALT` in `.env`
+3. **Don't return passwords** - User object should never include password
+4. **Validate on server** - Never trust client-side authentication
+5. **Use HTTPS in production** - Protect credentials in transit
+6. **Rate limit login attempts** - Prevent brute force attacks
+7. **Log authentication events** - Track successful and failed logins
+
+## Examples from miolo-sample
+
+See actual implementations:
+- `src/server/miolo/auth/credentials.mjs` - Default auth strategy
+- `src/server/db/io/users/auth.mjs` - User authentication query
+- `src/server/db/io/users/pwd.mjs` - Password change logic
+- `src/server/utils/crypt.mjs` - Hashing utilities