odac 1.3.0 → 1.4.1

package/docs/ai/README.md

@@ -0,0 +1,49 @@
+# ODAC AI Agent Master Guide
+
+Welcome! If you are reading this document, you are an AI Agent tasked with developing a project using the ODAC (Open Distributed Application Container) Framework.
+
+ODAC is a high-performance, enterprise-grade, and zero-configuration Node.js framework. Your mission is to produce secure, scalable code while strictly adhering to the framework's principles.
+
+## Core Mandate
+When developing with ODAC, you must not only write code but also leverage the framework's optimized structures (Route, View, Database, Hub, etc.) in the most efficient way possible.
+
+## Agent Principles
+1.  **Performance Focused**: Always aim for O(1) or O(n log n) complexity. Avoid inefficient queries like `SELECT *`.
+2.  **Security-by-Default**: Validate all input data using the `Validator`. Trust the auto-sanitizing View engine but maintain manual control in critical areas.
+3.  **Error Management**: Never swallow errors. Use framework-specific methods like `Odac.Request.error()` to return structured error messages.
+4.  **Clean Code**: Keep functions small (Single Responsibility) and adhere to ESM (ES Modules) standards.
+
+## How to Use This Guide
+The `skills/` directory contains a master `SKILL.md` that indexes specialized rules for each module. When adding a feature, you MUST refer to these rules and base your implementation on the "Reference Patterns".
+
+## Core Rules
+Detailed instructions are organized into Backend and Frontend categories:
+
+### Backend
+- `backend/authentication.md`: Sessions, Auth, and Realtime Hubs.
+- `backend/config.md`: Configuration management and environment variables.
+- `backend/controllers.md`: Request handling and Class-Based Controllers.
+- `backend/cron.md`: Scheduled background tasks and automation.
+- `backend/database.md`: High-performance query builder usage.
+- `backend/forms.md`: Form processing and validation logic.
+- `backend/ipc.md`: Inter-Process Communication and state sharing.
+- `backend/mail.md`: Transactional email sending.
+- `backend/request_response.md`: Handling Odac.Request and Odac.Response.
+- `backend/routing.md`: Route definitions, Middlewares, and Error Pages.
+- `backend/storage.md`: Persistent key-value storage (LMDB).
+- `backend/streaming.md`: Server-Sent Events (SSE) and Streaming API.
+- `backend/structure.md`: Project organization and Service Classes.
+- `backend/translations.md`: Multi-language support (i18n).
+- `backend/utilities.md`: Odac.Var (String Manipulation) and Flow Control.
+- `backend/validation.md`: Input sanitization and security checks.
+- `backend/views.md`: Template syntax, skeletons, and server-side JS.
+
+### Frontend
+- `frontend/core.md`: Framework lifecycle, page scoping, and storage.
+- `frontend/forms.md`: AJAX form handling and API requests.
+- `frontend/navigation.md`: AJAX Navigation (SPA) behavior.
+- `frontend/realtime.md`: WebSocket Hubs and EventSource usage.
+
+---
+
+**Remember:** You are an ODAC expert. Every line of code you write should reflect the "Enterprise" spirit of the framework.

package/docs/ai/skills/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: odac-framework-skill-catalog
+description: Comprehensive ODAC backend and frontend AI skill index for architecture, security, and high-performance application development.
+metadata:
+  tags: odac, skills, backend, frontend, architecture, security, performance
+---
+
+## When to use
+
+Use this skill whenever you are developing an application with the ODAC Framework. It provides domain-specific knowledge for both server-side logic and client-side interactions.
+
+## How to use
+
+Read the specific rule files based on whether you are working on the Backend or Frontend:
+
+### Backend Rules
+- [backend/authentication.md](backend/authentication.md) - Sessions, Auth, and Realtime Hubs
+- [backend/config.md](backend/config.md) - Configuration management and environment variables
+- [backend/controllers.md](backend/controllers.md) - Request handling and Class-Based Controllers
+- [backend/cron.md](backend/cron.md) - Scheduled background tasks and automation
+- [backend/database.md](backend/database.md) - Query Builder and DB best practices
+- [backend/forms.md](backend/forms.md) - Form processing and Validation logic
+- [backend/ipc.md](backend/ipc.md) - Inter-Process Communication and state sharing
+- [backend/mail.md](backend/mail.md) - Transactional email sending
+- [backend/migrations.md](backend/migrations.md) - Schema-first, auto-run, cluster-safe DB migrations
+- [backend/request_response.md](backend/request_response.md) - Handling Odac.Request and Odac.Response
+- [backend/routing.md](backend/routing.md) - Route definitions, Middlewares, and Error Pages
+- [backend/storage.md](backend/storage.md) - Persistent key-value storage (LMDB)
+- [backend/streaming.md](backend/streaming.md) - Server-Sent Events (SSE) and Streaming API
+- [backend/structure.md](backend/structure.md) - Project organization and Service Classes
+- [backend/translations.md](backend/translations.md) - Multi-language support (i18n)
+- [backend/utilities.md](backend/utilities.md) - Odac.Var (String Manipulation) and Flow Control
+- [backend/validation.md](backend/validation.md) - Input sanitization and security checks
+- [backend/views.md](backend/views.md) - Template syntax, skeletons, and server-side JS
+
+### Frontend Rules
+- [frontend/core.md](frontend/core.md) - Framework lifecycle, page scoping, and storage
+- [frontend/forms.md](frontend/forms.md) - AJAX form handling and API requests
+- [frontend/navigation.md](frontend/navigation.md) - AJAX Navigation (SPA) behavior
+- [frontend/realtime.md](frontend/realtime.md) - WebSocket Hubs and EventSource usage

package/docs/ai/skills/backend/authentication.md

@@ -0,0 +1,74 @@
+---
+name: backend-authentication-realtime-skill
+description: Secure ODAC authentication patterns for sessions, guards, passwordless flows, and realtime channel protection.
+metadata:
+  tags: backend, authentication, session, auth-guard, magic-link, realtime, security
+---
+
+# Backend Authentication & Realtime Skill
+
+Secure user authentication, session management, and bidirectional communication.
+
+## Architectural Approach
+ODAC provides built-in drivers for session handling (Memory/Redis) and multiple authentication flows including standard password-based login and passwordless Magic Links.
+
+## Core Rules
+1.  **Auth Guard**: Protect routes using `Odac.Route.auth`.
+2.  **Session Integrity**: `Odac.Request.setSession()` MUST be called before accessing `Odac.Request.session()`.
+3.  **Password Security**: The framework handles BCrypt hashing automatically via `Odac.Auth`.
+4.  **Magic Links**: Use `Odac.Auth.magic(email)` for passwordless flows.
+5.  **Token Rotation**: Enterprise-grade rotation is enabled by default. It uses a 60s grace period to prevent race conditions in SPAs.
+6.  **Persistence**: Cookies use the configured `maxAge` to persist beyond browser closure.
+## Reference Patterns
+
+### 1. Standard Login & Check
+```javascript
+// Check if user is logged in
+if (Odac.Auth.check()) {
+  const user = Odac.Auth.user();
+  const userId = Odac.Auth.id();
+}
+
+// Log in a user manually
+await Odac.Auth.login(userId);
+
+// Log out
+await Odac.Auth.logout();
+```
+
+### 2. Magic Links (Passwordless)
+```javascript
+// Generate and send a magic link
+const result = await Odac.Auth.magic('user@example.com', {
+  redirect: '/dashboard',
+  subject: 'Login to MyApp'
+});
+
+if (result.success) {
+  return { message: 'Link sent!' };
+}
+```
+
+### 3. Session Management
+```javascript
+// Get/Set session data
+Odac.session('key', 'value');
+const val = Odac.session('key');
+
+// Destroy session
+Odac.session('key', null);
+```
+
+### 4. Realtime Hubs (WebSockets)
+```javascript
+// Broadcast to everyone in a room
+Odac.Hub.to('lobby').send('chat_message', { text: 'Hello!' });
+
+// Targeted user broadcast
+Odac.Hub.user(userId).send('notification', { text: 'New follower' });
+```
+
+## Security Best Practices
+-   **CSRF Protection**: Native `Odac.form` and `Odac.post` handle CSRF tokens automatically using `{{ TOKEN }}` in views.
+-   **Brute Force**: Always use `validator.brute()` on authentication endpoints.
+-   **Passwordless Preference**: Consider using Magic Links for enhanced security and better user experience.

package/docs/ai/skills/backend/config.md

@@ -0,0 +1,39 @@
+---
+name: backend-configuration-skill
+description: ODAC configuration standards for odac.json usage, environment variable mapping, and secure runtime settings.
+metadata:
+  tags: backend, configuration, odac-json, environment, secrets, settings
+---
+
+# Backend Configuration Skill
+
+Managing application settings using `odac.json` and environment variables.
+
+## Architectural Approach
+ODAC uses `odac.json` for structure and `.env` for secrets. Values can be accessed via `Odac.Config` or the `Odac.env()` helper.
+
+## Core Rules
+1.  **Direct Access**: Use `Odac.Config.key` for settings in `odac.json`.
+2.  **Environment Variables**: Use `${VAR_NAME}` in `odac.json` to map to `.env` values.
+3.  **Encapsulation**: Never hardcode credentials. Always use `.env`.
+
+## Reference Patterns
+### 1. Accessing Config
+```javascript
+// From odac.json: { "app": { "name": "My App" } }
+const appName = Odac.Config.app.name;
+
+// From .env: API_KEY=secret
+const apiKey = Odac.env('API_KEY');
+```
+
+### 2. odac.json Structure
+```json
+{
+  "mysql": {
+    "host": "${DB_HOST}",
+    "password": "${DB_PASSWORD}"
+  },
+  "debug": true
+}
+```

package/docs/ai/skills/backend/controllers.md

@@ -0,0 +1,69 @@
+---
+name: backend-controllers-skill
+description: Best practices for ODAC controller architecture, class-based routing, and clean request handling boundaries.
+metadata:
+  tags: backend, controllers, class-based, route-mapping, architecture, maintainability
+---
+
+# Backend Controllers Skill
+
+Controllers are the bridge between routes and views/services. This skill covers how to write clean, professional controllers in ODAC.
+
+## Architectural Approach
+ODAC supports both simple function-based controllers and class-based controllers. For enterprise-grade applications, class-based controllers are strongly recommended for better organization.
+
+## Core Rules
+1.  **Class-Based Controllers**: Use classes to group related logic. Each method handles a specific route.
+2.  **Naming Convention**: Controllers are usually PascalCase (e.g., `UserController.js`).
+3.  **Route Mapping**: Use the `ControllerName@MethodName` syntax in routes.
+4.  **Automatic Injection**: Methods receive the `Odac` instance as the first argument automatically.
+
+## Reference Patterns
+
+### 1. Class-Based Controller (Recommended)
+```javascript
+// controller/User.js
+class User {
+  // GET /users
+  async index(Odac) {
+    const users = await Odac.Service.get('User').all();
+    return Odac.View.make('user.list', { users });
+  }
+
+  // GET /users/{id}
+  async show(Odac) {
+    const id = Odac.Request.input('id');
+    const user = await Odac.Service.get('User').find(id);
+    return Odac.return(user);
+  }
+
+  // POST /users
+  async store(Odac) {
+    const data = Odac.Request.post();
+    // Logic to save user...
+    return { success: true };
+  }
+}
+
+module.exports = User;
+```
+
+### 2. Simple Function-Based Controller
+```javascript
+// controller/Home.js
+module.exports = function(Odac) {
+  return "Welcome to ODAC!";
+};
+```
+
+### 3. Usage in Routes
+```javascript
+// route/web.js
+Odac.Route.get('/users', 'User@index');
+Odac.Route.get('/home', 'Home'); // Auto-calls the exported function
+```
+
+## Best Practices
+-   **Keep it Thin**: Controllers should only handle request parsing and response formatting. Core logic belongs in **Services**.
+-   **Asynchronous Handling**: Always use `async/await` for database or network operations.
+-   **Structured Returns**: Use `Odac.return()` for JSON or `Odac.View.make()` for rendering.

package/docs/ai/skills/backend/cron.md

@@ -0,0 +1,57 @@
+---
+name: backend-cron-jobs-skill
+description: Reliable ODAC cron scheduling patterns for background automation, timing control, and safe execution design.
+metadata:
+  tags: backend, cron, scheduler, background-jobs, automation, timing
+---
+
+# Backend Cron Jobs Skill
+
+ODAC provides a built-in cron system for automating background tasks without external dependencies.
+
+## Architectural Approach
+Cron jobs are defined in routes and executed by the internal scheduler. They can use either external controller files (recommended) or inline functions.
+
+## Core Rules
+1.  **Definition**: Use `Odac.Route.cron('name')` to start a definition.
+2.  **Scheduling**: Use fluent methods like `.everyMinute(n)`, `.at('HH:MM')`, `.day(n)`, etc.
+3.  **Controllers**: Cron controllers should be in `controller/cron/`. They receive the `Odac` instance.
+4.  **Wildcard Warning**: If you specify an hour but no minute, it will run every minute during that hour. Always use `.at()` or specify the minute.
+
+## Reference Patterns
+
+### 1. File-Based Cron (Recommended)
+```javascript
+// route/cron.js
+Odac.Route.cron('cleanup').at('03:00'); // Runs daily at 03:00
+
+// controller/cron/cleanup.js
+module.exports = async (Odac) => {
+  console.log('Running nightly cleanup...');
+  await Odac.DB.table('logs').where('created_at', '<', 'NOW() - INTERVAL 30 DAY').delete();
+};
+```
+
+### 2. Inline Function Cron
+```javascript
+Odac.Route.cron(async () => {
+  const stats = await Odac.DB.table('orders').count();
+  console.log('Current orders:', stats);
+}).everyHour(1);
+```
+
+### 3. Raw Unix Cron Patterns
+```javascript
+// Run every 15 minutes
+Odac.Route.cron('sync').raw('*/15 * * * *');
+```
+
+## Available Schedulers
+-   `.minute(0-59)`, `.hour(0-23)`, `.day(1-31)`, `.month(1-12)`, `.weekDay(0-6)`.
+-   `.everyMinute(n)`, `.everyHour(n)`, `.everyDay(n)`.
+-   `.at('HH:MM')`: Shorthand for setting specific hour and minute.
+
+## Best Practices
+-   **Logging**: Always log the start and completion of background tasks to the console or a file.
+-   **Timeouts**: Be aware that long-running tasks might overlap if the interval is too short.
+-   **Service Injection**: Use Service Classes inside cron jobs to keep the logic clean.

package/docs/ai/skills/backend/database.md

@@ -0,0 +1,37 @@
+---
+name: backend-database-skill
+description: High-performance ODAC database querying patterns using the built-in query builder with secure and efficient data access.
+metadata:
+  tags: backend, database, query-builder, sql, indexing, performance, security
+---
+
+# Backend Database Skill
+
+High-performance database operations using the ODAC Query Builder.
+
+## Principles
+1.  **Directness**: Avoid ORM overhead. Use fluent Query Builder.
+2.  **Safety**: Always use parameterized queries (built-in).
+3.  **Efficiency**: Index foreign keys. No `SELECT *`.
+
+## Patterns
+```javascript
+const user = await Odac.DB.table('users')
+  .select('id', 'name', 'email')
+  .where('status', 'active')
+  .first();
+
+await Odac.DB.table('posts').insert({
+  title: 'Hello',
+  user_id: 1
+});
+```
+
+## Migration Awareness
+1.  **Schema-First**: Structural DB changes must be defined in `schema/*.js`.
+2.  **Auto-Migrate**: Migrations run automatically at startup from `Database.init()`.
+3.  **Cluster-Safe**: Migration execution is limited to primary process (`cluster.isPrimary`).
+4.  **Indexes**: Keep index definitions in schema so add/drop is managed automatically.
+5.  **Data Changes**: Use `migration/*.js` only for one-time data transformation.
+
+See: [migrations.md](./migrations.md)

package/docs/ai/skills/backend/forms.md

@@ -0,0 +1,26 @@
+---
+name: backend-forms-validation-skill
+description: Secure ODAC form processing workflow with validation, CSRF protection, and safe request-to-database handling.
+metadata:
+  tags: backend, forms, validation, csrf, input-security, request-processing
+---
+
+# Backend Forms & Validation Skill
+
+Processing form data securely and validating inputs.
+
+## Rules
+1.  **Validator**: Always use `Odac.Validator` for input.
+2.  **Auto-save**: Use `Odac.DB.table().save(Odac.Request.post())` for quick inserts.
+3.  **CSRF**: Ensure `{{ TOKEN }}` is in your HTML forms.
+
+## Patterns
+```javascript
+// Validation
+const check = Odac.Validator.run(Odac.Request.post(), {
+  email: 'required|email',
+  password: 'required|min:8'
+});
+
+if (check.failed()) return Odac.Request.error(check.errors());
+```

package/docs/ai/skills/backend/ipc.md

@@ -0,0 +1,62 @@
+---
+name: backend-ipc-skill
+description: ODAC inter-process communication guidance for memory and Redis drivers, shared state, and distributed coordination.
+metadata:
+  tags: backend, ipc, redis, cluster, distributed-state, synchronization
+---
+
+# Backend IPC (Inter-Process Communication) Skill
+
+ODAC provides a built-in IPC system to share data and sync states across application workers or multiple servers.
+
+## Architectural Approach
+IPC abstracts the underlying driver, allowing seamless transition between `memory` (Node.js cluster) and `redis` (multi-server scaling).
+
+## Core Rules
+1.  **Drivers**:
+    -   `memory`: Shared across local workers via Main process (Default).
+    -   `redis`: Shared across multiple servers/clusters.
+2.  **State Sharing**: Use `Odac.Ipc` for global key-value storage.
+3.  **Messaging**: Use Pub/Sub for worker-to-worker communication.
+
+## Reference Patterns
+
+### 1. Key-Value Storage
+```javascript
+// Set value with optional TTL (seconds)
+await Odac.Ipc.set('maintenance_mode', true);
+await Odac.Ipc.set('cache_key', { data: 123 }, 60);
+
+// Get value
+const status = await Odac.Ipc.get('maintenance_mode');
+
+// Delete value
+await Odac.Ipc.del('maintenance_mode');
+```
+
+### 2. Pub/Sub Messaging
+```javascript
+// Subscribe to a channel (usually in a service or app start)
+await Odac.Ipc.subscribe('notifications', (msg) => {
+  console.log('Received:', msg);
+});
+
+// Publish a message from any worker
+await Odac.Ipc.publish('notifications', { type: 'alert', text: 'System update' });
+```
+
+## Configuration
+In `odac.json` or a config provider:
+```json
+{
+  "ipc": {
+    "driver": "redis",
+    "redis": "default"
+  }
+}
+```
+
+## Best Practices
+-   **Async First**: All IPC operations are asynchronous.
+-   **TTL Usage**: Always set a TTL for temporary cache data to prevent memory bloat.
+-   **Scaling**: Switch to `redis` driver when deploying across multiple containers or servers.

package/docs/ai/skills/backend/mail.md

@@ -0,0 +1,41 @@
+---
+name: backend-mail-skill
+description: Transactional email integration patterns in ODAC using fluent mail APIs, templating, and transport configuration.
+metadata:
+  tags: backend, mail, smtp, transactional-email, templating, notifications
+---
+
+# Backend Mail Skill
+
+Sending transactional emails using the fluent `Odac.Mail` service.
+
+## Core Rules
+1.  **Transport**: Configured via `odac.json` (SMTP, etc.).
+2.  **Templating**: Combine with `Odac.Var().replace()` for dynamic content.
+3.  **Methods**: Use `Odac.Mail.send({ ... })`.
+
+## Reference Patterns
+### 1. Simple Email
+```javascript
+await Odac.Mail.send({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  body: '<h1>Hello!</h1>',
+  type: 'html' // default is text
+});
+```
+
+### 2. Template-based Email
+```javascript
+const template = 'Hello {{ name }}, welcome to {{ site }}!';
+const body = Odac.Var(template).replace({
+  '{{ name }}': user.name,
+  '{{ site }}': 'ODAC'
+});
+
+await Odac.Mail.send({
+  to: user.email,
+  subject: 'Registration Success',
+  body: body
+});
+```

package/docs/ai/skills/backend/migrations.md

@@ -0,0 +1,80 @@
+---
+name: backend-migrations-skill
+description: Schema-first ODAC migration strategy for deterministic database evolution, index sync, and cluster-safe execution.
+metadata:
+  tags: backend, migrations, schema, database-evolution, indexes, cluster-safety
+---
+
+# Backend Migrations Skill
+
+Schema-first, zero-config migration strategy for ODAC.
+
+## Architectural Approach
+ODAC migrations are **declarative**. The `schema/` directory is the single source of truth for final DB state. The migration engine diffs desired schema vs current DB and applies create/alter/drop operations automatically.
+
+## Core Rules
+1. **Source of Truth**: Always update `schema/*.js` files, not historical migration chains, for structural changes.
+2. **Auto Execution**: Migrations run automatically during app startup via `Database.init()`.
+3. **Cluster Safety**: Auto-migration runs only on `cluster.isPrimary` to prevent race conditions.
+4. **Index Sync**: Define indexes in schema; engine adds/removes them automatically.
+5. **Drop Behavior**: If a column/index is removed from schema, it is removed from DB on next startup.
+6. **Seeds**: Use `seed` + `seedKey` for idempotent reference data.
+7. **Data Transformations**: Use imperative files under `migration/` only for one-time data migration logic.
+
+## Reference Patterns
+### 1. Schema File (Final State)
+```javascript
+// schema/users.js
+'use strict'
+
+module.exports = {
+  columns: {
+    id: {type: 'increments'},
+    email: {type: 'string', length: 255, nullable: false},
+    role: {type: 'enum', values: ['admin', 'user'], default: 'user'},
+    timestamps: {type: 'timestamps'}
+  },
+  indexes: [
+    {columns: ['email'], unique: true}
+  ],
+  seed: [
+    {email: 'admin@example.com', role: 'admin'}
+  ],
+  seedKey: 'email'
+}
+```
+
+### 2. Multi-Database Layout
+```
+schema/
+  users.js            # default DB
+  analytics/
+    events.js         # analytics DB
+```
+
+### 3. Imperative Data Migration (One-Time)
+```javascript
+// migration/20260225_001_backfill_roles.js
+module.exports = {
+  async up(db) {
+    await db('users').whereNull('role').update({role: 'user'})
+  },
+  async down(db) {
+    await db('users').where('role', 'user').update({role: null})
+  }
+}
+```
+
+### 4. CLI Operations
+```bash
+npx odac migrate
+npx odac migrate:status
+npx odac migrate:rollback
+npx odac migrate:snapshot
+```
+
+## Performance and Safety Notes
+- Keep schema declarations deterministic and minimal.
+- Prefer additive changes; drops are destructive and should be intentional.
+- Ensure high-cardinality lookup columns are indexed in schema definitions.
+- For very large tables, plan expensive column rewrites as dedicated data migrations.

package/docs/ai/skills/backend/request_response.md

@@ -0,0 +1,42 @@
+---
+name: backend-request-response-skill
+description: ODAC request parsing and response composition patterns for consistent, secure, and predictable API behavior.
+metadata:
+  tags: backend, request, response, headers, status-codes, json, api
+---
+
+# Backend Request & Response Skill
+
+Handling incoming data and sending structured responses.
+
+## Core Rules
+1.  **Request Data**: 
+    -   `Odac.request('key')`: Auto-detect GET/POST (Recommended).
+    -   `Odac.Request.post('key')`: Targeted POST data.
+    -   `Odac.Request.get('key')`: Targeted URL parameters.
+2.  **Metadata**: Access `Odac.Request.method`, `Odac.Request.ip`, `Odac.Request.header('name')`.
+3.  **Returning Data**: 
+    -   `return { ... }`: Returns JSON.
+    -   `return Odac.return({ ... })`: Explicit JSON return.
+    -   `Odac.Response.header('Key', 'Value')`: Set custom headers.
+
+## Reference Patterns
+### 1. Unified Request Handling
+```javascript
+module.exports = async function(Odac) {
+  const name = await Odac.request('name');
+  const method = Odac.Request.method;
+  
+  if (method === 'POST') {
+    return { success: true, message: `Saved ${name}` };
+  }
+};
+```
+
+### 2. Header and Status Management
+```javascript
+module.exports = function(Odac) {
+  Odac.Response.header('Content-Type', 'text/plain');
+  return "Raw text response";
+};
+```