odac 1.4.0 → 1.4.2

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

@@ -1,19 +1,120 @@
+---
+name: backend-forms-validation-skill
+description: Practical ODAC form usage patterns for register/login, magic-login, custom actions, and automatic database insert.
+metadata:
+  tags: backend, forms, validation, register, login, magic-login, request-processing
+---
+
 # Backend Forms & Validation Skill
 
-Processing form data securely and validating inputs.
+ODAC forms for validation, authentication flows, and safe request handling.
 
 ## 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.
+1.  **Use ODAC form tags**: Prefer `<odac:register>`, `<odac:login>`, `<odac:magic-login>`, `<odac:form>` instead of manual raw form handlers.
+2.  **Do not add manual hidden security fields**: Keep forms clean and use ODAC defaults.
+3.  **Validation in template**: Define rules with `<odac:validate rule="..." message="..."/>`; they become both frontend HTML constraints and backend validator checks.
+4.  **Server-side enrichment**: Use `<odac:set>` for trusted fields (`compute`, `value`, `callback`, `if-empty`) instead of taking these values from user input.
+5.  **Action vs table**: In `<odac:form>`, use `table="..."` for automatic insert or `action="Class.method"` for custom business logic.
+
+## Form Type Variants
+
+### 1) Register Form
+```html
+<odac:register redirect="/dashboard" autologin="true">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Valid email required"/>
+  </odac:input>
+
+  <odac:input name="password" type="password" label="Password">
+    <odac:validate rule="required|minlen:8" message="Min 8 chars"/>
+  </odac:input>
+
+  <odac:set name="created_at" compute="now"/>
+  <odac:submit text="Register" loading="Processing..."/>
+</odac:register>
+```
+
+### 2) Login Form
+```html
+<odac:login redirect="/panel">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Email required"/>
+  </odac:input>
+
+  <odac:input name="password" type="password" label="Password">
+    <odac:validate rule="required" message="Password required"/>
+  </odac:input>
+
+  <odac:submit text="Login" loading="Logging in..."/>
+</odac:login>
+```
+
+### 3) Magic Login Form
+```html
+<odac:magic-login redirect="/dashboard" email-label="Work Email" submit-text="Send Link" />
+```
+
+```html
+<odac:magic-login redirect="/dashboard">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email" message="Valid email required"/>
+  </odac:input>
+  <odac:submit text="Send Magic Link" loading="Sending..."/>
+</odac:magic-login>
+```
+
+### 4) Custom Form with Automatic DB Insert
+```html
+<odac:form table="waitlist" redirect="/" success="Thank you!" clear="true">
+  <odac:input name="email" type="email" label="Email">
+    <odac:validate rule="required|email|unique" message="Email already exists"/>
+  </odac:input>
+
+  <odac:set name="created_at" compute="now"/>
+  <odac:set name="ip" compute="ip"/>
+  <odac:submit text="Join" loading="Joining..."/>
+</odac:form>
+```
+
+### 5) Custom Form with Controller Action
+```html
+<odac:form action="Contact.submit" clear="false">
+  <odac:input name="subject" type="text" label="Subject">
+    <odac:validate rule="required|minlen:3" message="Subject is too short"/>
+  </odac:input>
+  <odac:submit text="Send" loading="Sending..."/>
+</odac:form>
+```
 
-## Patterns
 ```javascript
-// Validation
-const check = Odac.Validator.run(Odac.Request.post(), {
-  email: 'required|email',
-  password: 'required|min:8'
-});
+module.exports = class Contact {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async submit(form) {
+    const data = form.data
+    if (!data.subject) return form.error('subject', 'Subject required')
+    return form.success('Message sent', '/thank-you')
+  }
+}
+```
 
-if (check.failed()) return Odac.Request.error(check.errors());
+## Field-Level Variants
+- **Input types**: `text`, `email`, `password`, `number`, `url`, `textarea`, `checkbox`.
+- **Validation mapping**: `required|minlen|maxlen|min|max|alpha|alphanumeric|numeric|email|url|accepted`.
+- **Pass-through attrs**: Unrecognized `<odac:input ...>` attributes are preserved into generated HTML input/textarea.
+- **Skip persistence**: Use `skip` on `<odac:input>` to validate a field but exclude it from final payload.
+- **Unique shorthand**: `unique` attribute on `<odac:input>` enables auth-register uniqueness list.
+
+## Patterns
+```javascript
+// Access validated data in action-driven custom form
+Odac.Route.class.post('/contact', class Contact {
+  async submit(form) {
+    const {email, message} = form.data
+    if (!email || !message) return form.error('_odac_form', 'Missing input')
+    return form.success('Saved successfully')
+  }
+})
 ```

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

@@ -1,3 +1,10 @@
+---
+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.

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

@@ -1,3 +1,10 @@
+---
+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.

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

@@ -0,0 +1,86 @@
+---
+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. **NanoID Columns**: `type: 'nanoid'` maps to string columns and missing values are auto-generated on insert/seed.
+8. **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: 'nanoid', primary: true},
+    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'
+}
+```
+
+### NanoID Notes
+- `length` can be customized: `{type: 'nanoid', length: 12, primary: true}`.
+- If seed rows omit the nanoid field, ODAC fills it automatically.
+- If seed rows provide an explicit nanoid value, ODAC keeps it unchanged.
+
+### 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

@@ -1,3 +1,10 @@
+---
+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.

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

@@ -1,3 +1,10 @@
+---
+name: backend-routing-middleware-skill
+description: High-performance ODAC routing and middleware orchestration for secure request pipelines and scalable URL mapping.
+metadata:
+  tags: backend, routing, middleware, pipeline, auth, performance, url-matching
+---
+
 # Backend Routing & Middleware Skill
 
 Routing manages the request pipeline, directing URLs to controllers while applying security and business logic via middlewares.

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

@@ -1,3 +1,10 @@
+---
+name: backend-persistent-storage-skill
+description: Embedded ODAC storage usage patterns with LMDB for sub-millisecond key-value persistence across workers.
+metadata:
+  tags: backend, storage, lmdb, key-value, persistence, high-performance
+---
+
 # Backend Persistent Storage Skill
 
 ODAC provides a high-performance, embedded key-value store using LMDB, exposed via `Odac.Storage`.

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

@@ -1,3 +1,10 @@
+---
+name: backend-streaming-sse-skill
+description: Server-Sent Events streaming patterns in ODAC for realtime one-way updates with safe connection lifecycle management.
+metadata:
+  tags: backend, streaming, sse, realtime, event-stream, connection-lifecycle
+---
+
 # Backend Streaming API Skill
 
 Real-time data streaming using Server-Sent Events (SSE).

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

@@ -1,3 +1,10 @@
+---
+name: backend-structure-services-skill
+description: ODAC project organization rules for directory structure, service classes, and request-scoped architecture.
+metadata:
+  tags: backend, structure, services, architecture, request-scope, organization
+---
+
 # Backend Structure & Services Skill
 
 ODAC follows a strictly organized directory structure and focuses on request-scoped architecture. This skill explains how to organize code and use Service Classes.
@@ -31,7 +38,7 @@ class User {
 
   async getProfile(id) {
     // Access database or auth via this.Odac
-    return await this.Odac.Db.table('users').where('id', id).first();
+    return await this.Odac.DB.table('users').where('id', id).first();
   }
 }
 module.exports = User;

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

@@ -1,3 +1,10 @@
+---
+name: backend-translations-i18n-skill
+description: Internationalization patterns in ODAC for locale files, placeholders, and multilingual rendering workflows.
+metadata:
+  tags: backend, i18n, translations, locale, placeholders, multilingual
+---
+
 # Backend Translations (i18n) Skill
 
 ODAC provides built-in support for internationalization, allowing for easy multi-language application development.

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

@@ -1,3 +1,10 @@
+---
+name: backend-utilities-skill
+description: Practical ODAC utility patterns for string processing, hashing, encryption, and request flow control.
+metadata:
+    tags: backend, utilities, strings, hashing, encryption, flow-control
+---
+
 # Backend Utilities Skill
 
 String manipulation, hashing, and flow control.

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

@@ -1,53 +1,160 @@
-# Backend Validation Skill
+---
+name: backend-validation-skill
+description: Detailed ODAC Validator usage for request validation, security checks, brute-force protection, and consistent API responses.
+metadata:
+  tags: backend, validation, fluent-api, input-security, brute-force, error-handling
+---
 
-The `Validator` service provides a fluent, chainable API for securing user input and enforcing business rules.
+# Backend Validation Skill
 
-## Architectural Approach
-Validation should happen as early as possible in the request lifecycle. The `Validator` service handles automatic error formatting and frontend integration.
+ODAC validation should be centralized with the fluent `Validator` API and returned in framework-standard result format.
 
 ## Core Rules
-1.  **Chaining**: Use the fluent API: `.post(key).check(rules).message(msg)`.
-2.  **Brute Force**: Protect sensitive endpoints with `.brute(attempts)`.
-3.  **Automatic Errors**: Use `await validator.error()` to check status and `await validator.result()` to return standardized JSON.
-4.  **Inverse Rules**: Use `!` to invert any rule (e.g., `!required`).
+1.  **Create validator per request**: Use `const validator = Odac.validator()`.
+2.  **Fail fast**: Run all checks, then immediately return on `await validator.error()`.
+3.  **Field-first messages**: Assign a specific `.message(...)` per check chain.
+4.  **Use standard result shape**: Return `await validator.result('Validation failed')` for errors.
+5.  **Protect sensitive flows**: Add `await validator.brute(n)` on login/reset/auth endpoints.
+
+## Minimal Flow
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+
+  validator.post('email').check('required|email').message('Valid email required')
+  validator.post('password').check('required|minlen:8').message('Password must be at least 8 characters')
+
+  if (await validator.error()) {
+    await validator.brute(5)
+    return await validator.result('Validation failed')
+  }
+
+  return await validator.success({ok: true})
+}
+```
+
+## API Surface
+- `post(key)`: Validate POST payload field.
+- `get(key)`: Validate querystring field.
+- `var(name, value)`: Validate computed/custom value.
+- `file(name)`: Validate uploaded file object.
+- `check(rules | boolean)`: Apply pipe rules or direct boolean validation.
+- `message(text)`: Set message for the latest check on current field.
+- `error()`: Runs validation and returns `true` if any error exists.
+- `result(message?, data?)`: Returns ODAC-standard response object.
+- `success(dataOrMessage?)`: Convenience wrapper for success payload.
+- `brute(maxAttempts = 5)`: Tracks failed attempts per hour/page/ip.
+
+## Rule Catalog
+
+### Type & format rules
+- `required`, `accepted`
+- `numeric`, `float`
+- `alpha`, `alphaspace`, `alphanumeric`, `alphanumericspace`, `username`
+- `email`, `ip`, `mac`, `domain`, `url`
+- `array`, `date`, `xss`
+
+### Length & value rules
+- `len:X`, `minlen:X`, `maxlen:X`
+- `min:X`, `max:X`
+- `equal:value`, `not:value`
+- `same:field`, `different:field`
+
+### String/date matching rules
+- `in:substring`, `notin:substring`
+- `regex:pattern`
+- `mindate:YYYY-MM-DD`, `maxdate:YYYY-MM-DD`
+
+### Auth/security rules
+- `usercheck`: Must be authenticated.
+- `user:field`: Input must match authenticated user field.
+- `disposable`: Email must be disposable.
+- `!disposable`: Email must not be disposable.
+
+### Inverse rules
+- Prefix any rule with `!` to invert: `!required`, `!email`, `!equal:admin`.
 
 ## Reference Patterns
 
-### 1. Standard Validation Chaining
+### 1) Multi-check per field with specific errors
 ```javascript
-module.exports = async function (Odac) {
-  const validator = Odac.Validator;
+module.exports = async Odac => {
+  const validator = Odac.validator()
 
   validator
-    .post('email').check('required|email').message('Valid email required')
-    .post('password').check('required|minlen:8').message('Password too short');
+    .post('password')
+    .check('required').message('Password is required')
+    .check('minlen:8').message('Minimum 8 characters')
+    .check('regex:[A-Z]').message('At least one uppercase letter')
+    .check('regex:[0-9]').message('At least one number')
 
   if (await validator.error()) {
-    return validator.result('Please fix input errors');
+    return await validator.result('Please fix input errors')
   }
 
-  // Proceed with validated data
-  return validator.success('Success');
-};
+  return await validator.success('Success')
+}
+```
+
+### 2) GET + POST + VAR together
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+  const plan = await Odac.request('plan')
+
+  validator.get('page').check('numeric|min:1').message('Invalid page')
+  validator.post('email').check('required|email|!disposable').message('Corporate email required')
+  validator.var('plan', plan).check('in:pro').message('Only pro plan is allowed')
+
+  if (await validator.error()) return await validator.result('Validation failed')
+  return await validator.success({ok: true})
+}
 ```
 
-### 2. Custom Variable and Security Validation
+### 3) Boolean check for business rules
 ```javascript
-validator.var('age', userAge).check('numeric|min:18').message('Must be 18+');
+module.exports = async Odac => {
+  const validator = Odac.validator()
+  const canPublish = await somePermissionCheck(Odac)
+
+  validator.post('title').check('required').message('Title required')
+  validator.var('permission', null).check(canPublish).message('No publish permission')
+
+  if (await validator.error()) return await validator.result('Validation failed')
+  return await validator.success('Published')
+}
+```
+
+### 4) Brute-force on auth endpoint
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+
+  validator.post('email').check('required|email').message('Email required')
+  validator.post('password').check('required').message('Password required')
+
+  if (await validator.error()) {
+    await validator.brute(5)
+    return await validator.result('Login failed')
+  }
 
-// Security checks
-validator.post('bio').check('xss').message('Malicious HTML detected');
-validator.var('auth', null).check('usercheck').message('Authentication required');
+  return await validator.success('OK')
+}
 ```
 
-### 3. Common Rules Reference
--   `required`, `email`, `numeric`, `username`, `url`, `ip`, `json`.
--   `len:X`, `minlen:X`, `maxlen:X`.
--   `mindate:YYYY-MM-DD`, `maxdate:YYYY-MM-DD`.
--   `regex:pattern`, `same:field`, `different:field`.
--   `!disposable`: Blocks temporary email providers.
+## Response Contract
+- **Success**:
+  - `result.success: true`
+  - optional `result.message`
+  - optional `data`
+- **Failure**:
+  - `result.success: false`
+  - `errors.{field}` map
+  - global errors may use `errors._odac_form`
 
 ## Best Practices
--   **Specific Messages**: Provide helpful error messages that guide the user.
--   **Security First**: Use the `xss` rule for any user-generated content that will be rendered later.
--   **Fail Fast**: Return the validation result immediately if `validator.error()` is true.
+- Keep validation at route/controller entry; do not defer to deep service layers.
+- Use separate `check()` calls when you need rule-specific messages.
+- Prefer `var()` for derived values instead of re-reading mutable request state.
+- Use `xss` for text fields that can later be rendered in HTML.
+- Always combine auth endpoints with `brute()` to reduce credential-stuffing risk.

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

@@ -1,3 +1,10 @@
+---
+name: backend-views-templates-skill
+description: ODAC server-side rendering guidelines for template performance, skeleton layouts, and safe output rendering.
+metadata:
+  tags: backend, views, templates, ssr, xss-protection, skeleton, rendering
+---
+
 # Backend Views & Templates Skill
 
 High-performance server-side rendering using ODAC's optimized template engine.

package/docs/ai/skills/frontend/core.md

@@ -1,3 +1,10 @@
+---
+name: frontend-core-skill
+description: Core ODAC frontend architecture patterns based on actions, lifecycle hooks, and event-driven UI behavior.
+metadata:
+  tags: frontend, odac-js, actions, lifecycle, events, ui-architecture
+---
+
 # Frontend Core Skill
 
 The foundational principles of the `odac.js` library for building reactive and interactive user interfaces.

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

@@ -1,21 +1,56 @@
+---
+name: frontend-forms-api-skill
+description: odac.js form submission patterns for parser-generated ODAC forms and predictable AJAX request handling.
+metadata:
+  tags: frontend, forms, ajax, odac-form, register, login, magic-login
+---
+
 # Frontend Forms & API Skill
 
-Handling AJAX form submissions and API requests.
+Handling ODAC AJAX form submissions generated from server-side form parsing.
 
 ## Rules
-1.  **Forms**: Use `odac.form('#id', callback)` for AJAX submission.
-2.  **Requests**: Use `odac.get()` and `odac.post()` for manual requests.
-3.  **Realtime**: Handle WebSocket events using Hub structures in `Odac.action()`.
+1.  **Bind by form selector**: Use `Odac.form({ form: 'selector' }, callback)` or short form `Odac.form('selector', callback)`.
+2.  **Leverage parser-generated forms**: `odac-register`, `odac-login`, `odac-magic-login`, and `odac-custom-form` are all auto-bound on page load and after every AJAX navigation.
+3.  **Expect JSON result shape**: Handle `result.success`, `result.message`, `result.redirect`, and `errors` in callback.
+4.  **Message/clear control**: Use `messages` and `clear` options for UX behavior.
 
 ## Patterns
 ```javascript
-// Form with automatic validation feedback
-odac.form('#my-form', (res) => {
-  if(res.success) odac.visit('/done');
-});
-
-// Simple API Check
-odac.get('/api/status', (data) => {
-  console.log('Status:', data);
-});
+// 1) Bind a parsed custom form
+Odac.form('form[data-odac-form]')
+
+// 2) Bind parsed register/login forms explicitly (optional)
+Odac.form('form[data-odac-register]')
+Odac.form('form[data-odac-login]')
+
+// 3) Bind parsed magic-login form manually
+Odac.form('form[data-odac-magic-login]', response => {
+  if (response?.result?.success && !response.result.redirect) {
+    const info = document.querySelector('[data-status]')
+    if (info) info.textContent = response.result.message
+  }
+})
+
+// 4) Advanced options: disable auto clear and hide success messages
+Odac.form(
+  {form: 'form[data-odac-form]', clear: false, messages: ['error']},
+  response => {
+    if (response?.result?.success && response.result.redirect) {
+      window.location.href = response.result.redirect
+    }
+  }
+)
+
+// 5) Manual GET request helper
+Odac.get('/api/status', data => {
+  const status = document.querySelector('[data-api-status]')
+  if (status) status.textContent = String(data?.status ?? '')
+})
 ```
+
+## Response Handling Contract
+- **Success**: `response.result.success === true`
+- **Redirect**: `response.result.redirect` exists when server wants navigation
+- **Form errors**: `response.errors.{fieldName}` maps to `odac-form-error="fieldName"`
+- **Global form error**: `response.errors._odac_form`

package/docs/ai/skills/frontend/navigation.md

@@ -1,3 +1,10 @@
+---
+name: frontend-navigation-spa-skill
+description: Single-page navigation patterns in odac.js for smooth transitions, route control, and lifecycle-safe execution.
+metadata:
+  tags: frontend, navigation, spa, ajax-navigation, page-lifecycle, transitions
+---
+
 # Frontend Navigation & SPA Skill
 
 Smooth transitions and single-page application behavior using `odac.js`.

package/docs/ai/skills/frontend/realtime.md

@@ -1,3 +1,10 @@
+---
+name: frontend-realtime-websocket-skill
+description: Realtime frontend communication patterns in odac.js using shared WebSockets, SSE, and resilient reconnect behavior.
+metadata:
+  tags: frontend, realtime, websocket, sse, sharedworker, auto-reconnect
+---
+
 # Frontend Realtime & WebSocket Skill
 
 Real-time bidirectional communication and server-sent events with high efficiency.