odac 1.4.1 → 1.4.3

package/.agent/rules/memory.md

@@ -43,6 +43,11 @@ trigger: always_on
 - **Mandatory Test Coverage:** Every new feature, method, or significant logic change MUST be accompanied by a corresponding unit or integration test.
     - **Verify Correctness:** do not assume code works; prove it with a test that covers both success and failure scenarios (e.g., edge cases, error conditions).
     - **Update Existing Tests:** If a feature modifies existing behavior, update the relevant tests to reflect the new logic and ensure they pass.
+- **Atomic Test Structure:**
+    - **Directory Mapping:** Each source class/module must have its own directory under `test/` (e.g., `src/Auth.js` -> `test/Auth/`).
+    - **Method-Level Files:** Every public method should have its own test file within the class directory (e.g., `test/Auth/check.test.js`).
+    - **Sub-module Context:** Nested modules should follow the same pattern (e.g., `src/View/Form.js` -> `test/View/Form/generateFieldHtml.test.js`).
+    - **Isolation & Parallelism:** This structure is mandatory to leverage Jest's multi-threaded execution and ensure strict isolation between test cases.
 
 ## Client Library (odac.js)
 - **Automatic JSON Parsing:** The `#ajax` method (and by extension `odac.get`) must automatically parse the response if the `Content-Type` header contains `application/json`, even if `dataType` is not explicitly set to `json`.

package/.releaserc.js

@@ -4,7 +4,12 @@ module.exports = {
     [
       '@semantic-release/commit-analyzer',
       {
-        preset: 'conventionalcommits'
+        preset: 'conventionalcommits',
+        releaseRules: [
+          {type: 'major', release: 'major'},
+          {type: 'minor', release: 'minor'},
+          {type: '*', release: 'patch'}
+        ]
       }
     ],
     [
@@ -16,6 +21,8 @@ module.exports = {
             const commit = JSON.parse(JSON.stringify(c))
 
             const map = {
+              major: '🚀 Major Updates',
+              minor: '🌟 Minor Updates',
               feat: "✨ What's New",
               fix: '🛠️ Fixes & Improvements',
               perf: '⚡️ Performance Upgrades',
@@ -134,4 +141,4 @@ Powered by [⚡ ODAC](https://odac.run)
     ],
     '@semantic-release/github'
   ]
-}
+}

package/CHANGELOG.md

@@ -1,3 +1,67 @@
+### ⚙️ Engine Tuning
+
+- **client:** extract ws connection logic and fix recursive sharedworker reconnects reconnect bug
+- **client:** remove redundant truthy check for websocket token
+- **route:** remove useless variable assignment for decodedUrl
+
+### ⚡️ Performance Upgrades
+
+- **client:** remove redundant token consumption during websocket initialization
+
+### 📚 Documentation
+
+- **README:** enhance security section with detailed CSRF protection features
+
+### 🛠️ Fixes & Improvements
+
+- **client:** enhance websocket reconnection logic with attempt tracking and timer management
+- **client:** preserve existing websocket subprotocols & add try/catch layer to token provider
+- **route:** improve URL decoding and public path handling for file requests
+- **route:** sanitize decoded URL and improve public path validation
+- **route:** use robust path.extname instead of string splitting for mime type resolution
+- **websocket:** implement token provider for dynamic token handling on reconnect
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### doc
+
+- **forms:** update backend and frontend forms documentation with practical usage patterns and improved descriptions
+- **validation:** enhance backend validation documentation with detailed usage patterns and examples
+
+### ⚙️ Engine Tuning
+
+- **test:** restructure test suite into class-scoped directories and method-level atomic files
+
+### ✨ What's New
+
+- **database:** add debug logging for schema parsing failures in nanoid metadata loader
+- **database:** introduce NanoID support for automatic ID generation in schema
+- **release:** enhance commit analyzer with release rules and custom labels
+- **shutdown:** implement graceful shutdown for IPC, Database, and Cron services
+
+### 📚 Documentation
+
+- **database:** remove underscore from nanoid example to reflect true alphanumeric output
+
+### 🛠️ Fixes & Improvements
+
+- **Auth:** handle token rotation for WebSocket connections and update active timestamp
+- **core:** explicitly stop session GC interval during graceful shutdown
+- **database:** namespace nanoid schema cache by connection to prevent table to prevent collisions
+- **forms:** initialize ODAC form handlers on DOMContentLoaded and after AJAX navigation
+- **manageSkills:** correct targetPath assignment for skill synchronization
+- **Validator:** pass Odac instance to Validator for improved access to global methods
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### doc
 
 - enhance AI skills documentation with structured YAML front matter and detailed descriptions

package/README.md

@@ -9,7 +9,7 @@
 *   🎨 **Built-in Tailwind CSS:** Zero-config integration with Tailwind CSS v4. Automatic compilation and optimization out of the box.
 *   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
 *   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
-*   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
+*   🛡️ **Built-in Security:** Enterprise-grade security out of the box. Includes secure default headers and a **Multi-tab Safe, Single-Use CSRF Protection (Nonce)**. Tokens self-replenish in the background, ensuring maximum defense without ever interrupting the user experience.
 *   🔐 **Authentication:** Ready-to-use session management with enterprise-grade **Refresh Token Rotation**, secure password hashing, and authentication helpers.
 *   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
 *   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.

package/bin/odac.js

@@ -210,7 +210,7 @@ async function manageSkills(targetDir = process.cwd()) {
   }
 
   const targetBase = path.resolve(targetDir, targetSubDir)
-  const targetPath = targetBase
+  const targetPath = copySkillsOnly ? path.join(targetBase, 'odac.js') : targetBase
 
   try {
     fs.mkdirSync(targetPath, {recursive: true})
@@ -222,7 +222,8 @@ async function manageSkills(targetDir = process.cwd()) {
       fs.cpSync(aiSourceDir, targetPath, {recursive: true})
     }
 
-    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${targetSubDir}\x1b[0m`)
+    const finalSubDir = copySkillsOnly ? path.join(targetSubDir, 'odac.js') : targetSubDir
+    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${finalSubDir}\x1b[0m`)
     console.log('Your AI Agent now has full knowledge of the ODAC Framework. 🚀')
   } catch (err) {
     console.error('❌ Failed to sync AI skills:', err.message)

package/client/odac.js

@@ -7,10 +7,12 @@ class OdacWebSocket {
   #reconnectAttempts = 0
   #handlers = {}
   #isClosed = false
+  #tokenProvider = null
 
   constructor(url, protocols = [], options = {}) {
     this.#url = url
     this.#protocols = protocols
+    this.#tokenProvider = options.tokenProvider || null
     this.#options = {
       autoReconnect: true,
       reconnectDelay: 3000,
@@ -23,6 +25,19 @@ class OdacWebSocket {
   connect() {
     if (this.#isClosed) return
 
+    if (this.#tokenProvider) {
+      try {
+        const freshToken = this.#tokenProvider()
+        if (freshToken) {
+          let current = Array.isArray(this.#protocols) ? this.#protocols : this.#protocols ? [this.#protocols] : []
+          this.#protocols = current.filter(p => !p.startsWith('odac-token-'))
+          this.#protocols.push(`odac-token-${freshToken}`)
+        }
+      } catch (e) {
+        console.error('Odac WebSocket tokenProvider error:', e)
+      }
+    }
+
     this.#socket = this.#protocols.length > 0 ? new WebSocket(this.#url, this.#protocols) : new WebSocket(this.#url)
 
     this.#socket.onopen = () => {
@@ -111,6 +126,12 @@ if (typeof window !== 'undefined') {
       // In constructor we can't call this.data() easily if it uses 'this' for caching properly before init
       // But based on original code logic:
       this.#data = this.data()
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => this.#initForms())
+      } else {
+        this.#initForms()
+      }
     }
 
     #ajax(options) {
@@ -795,6 +816,8 @@ if (typeof window !== 'undefined') {
     }
 
     #handleLoadComplete(data, callback) {
+      this.#initForms()
+
       if (this.actions.load)
         (Array.isArray(this.actions.load) ? this.actions.load : [this.actions.load]).forEach(fn => fn(this.page(), data.variables))
       if (this.actions.page && this.actions.page[this.page()])
@@ -808,6 +831,30 @@ if (typeof window !== 'undefined') {
       this.#isNavigating = false
     }
 
+    /**
+     * Scans the DOM for ODAC form components and registers submit handlers
+     * for any that haven't been initialized yet. Called on DOMContentLoaded
+     * and after every AJAX navigation to bind freshly rendered forms.
+     */
+    #initForms() {
+      const formTypes = [
+        {cls: 'odac-register-form', attr: 'data-odac-register'},
+        {cls: 'odac-login-form', attr: 'data-odac-login'},
+        {cls: 'odac-magic-login-form', attr: 'data-odac-magic-login'},
+        {cls: 'odac-custom-form', attr: 'data-odac-form'}
+      ]
+
+      for (const {cls, attr} of formTypes) {
+        document.querySelectorAll(`form.${cls}[${attr}]`).forEach(form => {
+          const token = form.getAttribute(attr)
+          const selector = `form[${attr}="${token}"]`
+          if (!this.#formSubmitHandlers.has(selector)) {
+            this.form({form: selector})
+          }
+        })
+      }
+    }
+
     loader(selector, elements, callback) {
       this.#loader.elements = elements
       this.#loader.callback = callback
@@ -892,12 +939,9 @@ if (typeof window !== 'undefined') {
       const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
       const wsUrl = `${protocol}//${window.location.host}${path}`
       const protocols = []
-      if (token) {
-        const csrfToken = this.token()
-        if (csrfToken) protocols.push(`odac-token-${csrfToken}`)
-      }
+      const tokenProvider = token ? () => this.token() : null
 
-      return new OdacWebSocket(wsUrl, protocols, options)
+      return new OdacWebSocket(wsUrl, protocols, {...options, tokenProvider})
     }
 
     #createSharedWebSocket(path, options) {
@@ -934,6 +978,9 @@ if (typeof window !== 'undefined') {
           case 'error':
             emit('error', data)
             break
+          case 'requestToken':
+            worker.port.postMessage({type: 'provideToken', token: this.token()})
+            break
         }
       }
 
@@ -993,25 +1040,73 @@ if (typeof window !== 'undefined') {
     }
     document.readyState === 'loading' ? document.addEventListener('DOMContentLoaded', init) : init()
   })()
-
-  document.addEventListener('DOMContentLoaded', () => {
-    ;['register', 'login'].forEach(type => {
-      document.querySelectorAll(`form.odac-${type}-form[data-odac-${type}]`).forEach(form => {
-        const token = form.getAttribute(`data-odac-${type}`)
-        window.Odac.form({form: `form[data-odac-${type}="${token}"]`})
-      })
-    })
-    document.querySelectorAll('form.odac-custom-form[data-odac-form]').forEach(form => {
-      const token = form.getAttribute('data-odac-form')
-      window.Odac.form({form: `form[data-odac-form="${token}"]`})
-    })
-  })
 } else {
   let socket = null
   const ports = new Set()
 
   const broadcast = (type, data) => ports.forEach(port => port.postMessage({type, data}))
 
+  let wsConfig = null
+  let reconnectAttempts = 0
+  let reconnectTimer = null
+
+  const requestTokenFromPort = () => {
+    return new Promise(resolve => {
+      const firstPort = ports.values().next().value
+      if (!firstPort) return resolve(null)
+
+      let timeoutTimer = null
+
+      const handler = event => {
+        if (event.data.type === 'provideToken') {
+          clearTimeout(timeoutTimer)
+          firstPort.removeEventListener('message', handler)
+          resolve(event.data.token)
+        }
+      }
+
+      timeoutTimer = setTimeout(() => {
+        firstPort.removeEventListener('message', handler)
+        resolve(null)
+      }, 5000)
+
+      firstPort.addEventListener('message', handler)
+      firstPort.postMessage({type: 'requestToken'})
+    })
+  }
+
+  const connectSocket = protocols => {
+    if (!wsConfig || ports.size === 0) return
+    const wsUrl = wsConfig.protocol + '//' + wsConfig.host + wsConfig.path
+    socket = new OdacWebSocket(wsUrl, protocols, {
+      ...wsConfig.options,
+      tokenProvider: null
+    })
+    socket.on('open', () => {
+      reconnectAttempts = 0
+      broadcast('open')
+    })
+    socket.on('message', data => broadcast('message', data))
+    socket.on('close', e => {
+      broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean})
+      const maxAttempts = wsConfig.options.maxReconnectAttempts || 10
+      if (wsConfig && wsConfig.options.autoReconnect !== false && ports.size > 0 && reconnectAttempts < maxAttempts) {
+        if (socket) {
+          socket.close()
+          socket = null
+        }
+        reconnectAttempts++
+        reconnectTimer = setTimeout(() => {
+          requestTokenFromPort().then(freshToken => {
+            if (!freshToken || ports.size === 0) return
+            connectSocket(['odac-token-' + freshToken])
+          })
+        }, wsConfig.options.reconnectDelay || 1000)
+      }
+    })
+    socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+  }
+
   self.onconnect = e => {
     const port = e.ports[0]
     ports.add(port)
@@ -1022,15 +1117,10 @@ if (typeof window !== 'undefined') {
       switch (type) {
         case 'connect':
           if (!socket) {
-            const wsUrl = protocol + '//' + host + path
+            wsConfig = {host, path, protocol, options}
             const protocols = token ? ['odac-token-' + token] : []
-            socket = new OdacWebSocket(wsUrl, protocols, options)
-            socket.on('open', () => broadcast('open'))
-            socket.on('message', data => broadcast('message', data))
-            socket.on('close', e => broadcast('close', {code: e?.code, reason: e?.reason, wasClean: e?.wasClean}))
-            socket.on('error', e => broadcast('error', {message: e?.message || 'WebSocket error'}))
+            connectSocket(protocols)
           } else if (socket.connected) {
-            // If already connected, notify the new port immediately
             port.postMessage({type: 'open'})
           }
           break
@@ -1039,9 +1129,15 @@ if (typeof window !== 'undefined') {
           break
         case 'close':
           ports.delete(port)
-          if (ports.size === 0 && socket) {
-            socket.close()
-            socket = null
+          if (ports.size === 0) {
+            if (reconnectTimer) {
+              clearTimeout(reconnectTimer)
+              reconnectTimer = null
+            }
+            if (socket) {
+              socket.close()
+              socket = null
+            }
           }
           break
       }

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

@@ -27,6 +27,25 @@ await Odac.DB.table('posts').insert({
 });
 ```
 
+## ID Strategy (NanoID)
+1.  **Schema-Driven**: Define string IDs with `type: 'nanoid'` in `schema/*.js`.
+2.  **Auto Generation**: On `insert()`, ODAC auto-generates missing nanoid fields.
+3.  **No Override**: If ID is explicitly provided, ODAC preserves it.
+4.  **Bulk Safe**: Auto-generation works for both single and bulk inserts.
+
+```javascript
+// schema/posts.js
+module.exports = {
+  columns: {
+    id: {type: 'nanoid', primary: true},
+    title: {type: 'string', length: 255}
+  }
+}
+
+// ID is generated automatically
+await Odac.DB.table('posts').insert({title: 'Hello'});
+```
+
 ## 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()`.

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

@@ -1,26 +1,120 @@
 ---
 name: backend-forms-validation-skill
-description: Secure ODAC form processing workflow with validation, CSRF protection, and safe request-to-database handling.
+description: Practical ODAC form usage patterns for register/login, magic-login, custom actions, and automatic database insert.
 metadata:
-  tags: backend, forms, validation, csrf, input-security, request-processing
+  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/migrations.md

@@ -19,7 +19,8 @@ ODAC migrations are **declarative**. The `schema/` directory is the single sourc
 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.
+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)
@@ -29,7 +30,7 @@ ODAC migrations are **declarative**. The `schema/` directory is the single sourc
 
 module.exports = {
   columns: {
-    id: {type: 'increments'},
+    id: {type: 'nanoid', primary: true},
     email: {type: 'string', length: 255, nullable: false},
     role: {type: 'enum', values: ['admin', 'user'], default: 'user'},
     timestamps: {type: 'timestamps'}
@@ -44,6 +45,11 @@ module.exports = {
 }
 ```
 
+### 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/