odac 1.4.0 → 1.4.2

package/.agent/rules/memory.md

@@ -36,10 +36,18 @@ trigger: always_on
 ## Naming & Text Conventions
 - **ODAC Casing:** Always write "ODAC" in uppercase letters when referring to the framework name in strings, comments, log messages, or user-facing text. **EXCEPTION:** The class name itself (`class Odac`) and variable references to it should remain `Odac` (PascalCase) as per code conventions.
 
+## Documentation Standards
+- **AI Skill Front Matter:** Every file under `docs/ai/skills/**/*.md` must start with YAML front matter containing `name`, `description`, and `metadata.tags`; values must be specific to that document's topic (never copied from generic examples).
+
 ## Testing & Validation
 - **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/.github/workflows/release.yml

@@ -62,6 +62,7 @@ jobs:
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           michelangelo: ${{ secrets.MICHELANGELO }}
+          version: ${{ steps.version.outputs.version }}
         timeout-minutes: 15
         continue-on-error: true
 
@@ -96,7 +97,6 @@ jobs:
         if: steps.ai_notes.outcome == 'success' && steps.version.outputs.version != ''
         with:
           tag_name: v${{ steps.version.outputs.version }}
-          name: ${{ steps.ai_notes.outputs.release-title }}
           body_path: RELEASE_NOTE.md
           draft: false
           prerelease: false

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,64 @@
+### 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
+
+### ⚙️ Engine Tuning
+
+- **database:** centralize knex connection bootstrap for runtime and CLI
+
+### 📚 Documentation
+
+- add section for loading and updating AI skills in projects
+
+### 🛠️ Fixes & Improvements
+
+- **auth:** improve token rotation logic and ensure proper cookie attributes
+- **cli:** parse .env values consistently in migration loader
+- **config:** update interpolation regex to support variable names with hyphens
+- **migration:** normalize column-level unique constraints and enhance idempotency in migrations
+- **release:** add version output to release notes and update release title condition
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### ⚙️ Engine Tuning
 
 - Extract MIME type definitions into a dedicated module.

package/README.md

@@ -53,6 +53,16 @@ cd my-app
 npm run dev
 ```
 
+## 🤖 AI Skills in Projects
+
+Load or update ODAC skills from your project root with:
+
+```bash
+npx odac skills
+```
+
+This command syncs built-in skills to your selected AI tool folder and can be re-run anytime to update them.
+
 ## 📂 Project Structure
 
 ```

package/bin/odac.js

@@ -5,6 +5,8 @@ const path = require('node:path')
 const readline = require('node:readline')
 const {execSync, spawn} = require('node:child_process')
 const cluster = require('node:cluster')
+const Env = require('../src/Env')
+const {buildConnections} = require('../src/Database/ConnectionFactory')
 
 const command = process.argv[2]
 const args = process.argv.slice(3)
@@ -208,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})
@@ -220,13 +222,196 @@ 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)
   }
 }
 
+/**
+ * Bootstraps the database and migration engine, then executes the requested migration command.
+ * Why: Migration commands need DB connections but not the full server stack.
+ * @param {string} cmd - The migration subcommand
+ * @param {string[]} cliArgs - CLI arguments (e.g. --db=analytics)
+ */
+async function runMigration(cmd, cliArgs) {
+  const projectDir = process.cwd()
+  const envPath = path.join(projectDir, '.env')
+  const configPath = path.join(projectDir, 'odac.json')
+
+  // Load .env
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, 'utf8')
+    envContent.split('\n').forEach(line => {
+      line = line.trim()
+      if (!line || line.startsWith('#')) return
+      const idx = line.indexOf('=')
+      if (idx === -1) return
+      const key = line.slice(0, idx).trim()
+      const value = Env._parseValue(line.slice(idx + 1).trim())
+      if (process.env[key] === undefined) process.env[key] = value
+    })
+  }
+
+  // Load config
+  if (!fs.existsSync(configPath)) {
+    console.error('❌ No odac.json found in current directory.')
+    process.exit(1)
+  }
+
+  let config
+  try {
+    let raw = fs.readFileSync(configPath, 'utf8')
+    config = JSON.parse(raw)
+    // Interpolate env vars safely by traversing parsed object values.
+    const interpolateConfig = input => {
+      if (typeof input === 'string') {
+        return input.replace(/\$\{([^{}]+)\}/g, (_, key) => process.env[key] || '')
+      }
+
+      if (Array.isArray(input)) {
+        return input.map(item => interpolateConfig(item))
+      }
+
+      if (input && typeof input === 'object') {
+        const output = {}
+        for (const key of Object.keys(input)) {
+          output[key] = interpolateConfig(input[key])
+        }
+        return output
+      }
+
+      return input
+    }
+
+    config = interpolateConfig(config)
+  } catch (err) {
+    console.error('❌ Failed to parse odac.json:', err.message)
+    process.exit(1)
+  }
+
+  const dbConfig = config.database
+  if (!dbConfig) {
+    console.error('❌ No database configuration found in odac.json.')
+    process.exit(1)
+  }
+
+  const connections = buildConnections(dbConfig)
+
+  for (const key of Object.keys(connections)) {
+    try {
+      await connections[key].raw('SELECT 1')
+    } catch (e) {
+      console.error(`❌ Failed to connect to '${key}' database:`, e.message)
+      process.exit(1)
+    }
+  }
+
+  // Parse --db flag
+  const dbFlag = cliArgs.find(a => a.startsWith('--db='))
+  const options = dbFlag ? {db: dbFlag.split('=')[1]} : {}
+
+  // Initialize migration engine
+  const Migration = require('../src/Database/Migration')
+  Migration.init(projectDir, connections)
+
+  try {
+    if (cmd === 'migrate') {
+      console.log('🔄 Running migrations...\n')
+      const summary = await Migration.migrate(options)
+      printMigrationSummary(summary)
+    } else if (cmd === 'migrate:status') {
+      console.log('📋 Migration Status (dry-run):\n')
+      const summary = await Migration.status(options)
+      printMigrationSummary(summary)
+    } else if (cmd === 'migrate:rollback') {
+      console.log('⏪ Rolling back last batch...\n')
+      const summary = await Migration.rollback(options)
+      printMigrationSummary(summary)
+    } else if (cmd === 'migrate:snapshot') {
+      console.log('📸 Generating schema files from database...\n')
+      const result = await Migration.snapshot(options)
+      for (const [key, files] of Object.entries(result)) {
+        console.log(`  \x1b[36m${key}\x1b[0m: ${files.length} schema file(s) generated`)
+        for (const f of files) {
+          console.log(`    → ${path.relative(projectDir, f)}`)
+        }
+      }
+      console.log('\n✅ Snapshot complete.')
+    }
+  } catch (err) {
+    console.error('❌ Migration error:', err.message)
+    process.exit(1)
+  } finally {
+    for (const conn of Object.values(connections)) {
+      await conn.destroy()
+    }
+  }
+}
+
+/**
+ * Formats and prints migration operation summary to stdout.
+ * @param {object} summary - Migration result per connection
+ */
+function printMigrationSummary(summary) {
+  let totalOps = 0
+
+  for (const [key, result] of Object.entries(summary)) {
+    console.log(`  \x1b[36m[${key}]\x1b[0m`)
+
+    const allOps = [...(result.schema || []), ...(result.files || []), ...(result.seeds || [])]
+
+    if (allOps.length === 0) {
+      console.log('    Nothing to do.')
+    }
+
+    for (const op of allOps) {
+      totalOps++
+      const label = formatOp(op)
+      console.log(`    ${label}`)
+    }
+    console.log('')
+  }
+
+  console.log(totalOps > 0 ? `✅ ${totalOps} operation(s) completed.` : '✅ Everything is up to date.')
+}
+
+/**
+ * Formats a single migration operation for CLI display.
+ * @param {object} op - Operation descriptor
+ * @returns {string} Formatted label
+ */
+function formatOp(op) {
+  switch (op.type) {
+    case 'create_table':
+      return `\x1b[32m+ CREATE TABLE\x1b[0m ${op.table}`
+    case 'add_column':
+      return `\x1b[32m+ ADD COLUMN\x1b[0m ${op.table}.${op.column}`
+    case 'drop_column':
+      return `\x1b[31m- DROP COLUMN\x1b[0m ${op.table}.${op.column}`
+    case 'alter_column':
+      return `\x1b[33m~ ALTER COLUMN\x1b[0m ${op.table}.${op.column}`
+    case 'add_index':
+      return `\x1b[32m+ ADD INDEX\x1b[0m ${op.table} (${op.index.columns.join(', ')})`
+    case 'drop_index':
+      return `\x1b[31m- DROP INDEX\x1b[0m ${op.table} (${op.index.columns.join(', ')})`
+    case 'pending_file':
+      return `\x1b[33m⏳ PENDING\x1b[0m ${op.name}`
+    case 'applied_file':
+      return `\x1b[32m✓ APPLIED\x1b[0m ${op.name}`
+    case 'rolled_back':
+      return `\x1b[33m↩ ROLLED BACK\x1b[0m ${op.name}`
+    case 'seed_insert':
+      return `\x1b[32m+ SEED INSERT\x1b[0m ${op.table} (${op.key})`
+    case 'seed_update':
+      return `\x1b[33m~ SEED UPDATE\x1b[0m ${op.table} (${op.key})`
+    default:
+      return `  ${op.type}`
+  }
+}
+
 async function run() {
   if (command === 'init') {
     const projectName = args[0] || '.'
@@ -376,6 +561,8 @@ async function run() {
     require('../index.js')
   } else if (command === 'skills') {
     await manageSkills()
+  } else if (command === 'migrate' || command === 'migrate:status' || command === 'migrate:rollback' || command === 'migrate:snapshot') {
+    await runMigration(command, args)
   } else {
     console.log('Usage:')
     console.log('  npx odac init            (Interactive mode)')
@@ -384,6 +571,10 @@ async function run() {
     console.log('  npx odac build           (Production build)')
     console.log('  npx odac start           (Start server)')
     console.log('  npx odac skills          (Sync AI Agent skills)')
+    console.log('  npx odac migrate         (Run pending migrations)')
+    console.log('  npx odac migrate:status  (Show pending changes)')
+    console.log('  npx odac migrate:rollback (Rollback last batch)')
+    console.log('  npx odac migrate:snapshot (Reverse-engineer DB to schema/)')
   }
 
   rl.close()

package/client/odac.js

@@ -111,6 +111,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 +801,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 +816,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
@@ -993,19 +1025,6 @@ 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()

package/docs/ai/skills/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: odac-framework
-description: Comprehensive AI developer skills for the ODAC Framework (Backend & Frontend).
+name: odac-framework-skill-catalog
+description: Comprehensive ODAC backend and frontend AI skill index for architecture, security, and high-performance application development.
 metadata:
-  tags: nodejs, framework, backend, frontend, architecture, security
+  tags: odac, skills, backend, frontend, architecture, security, performance
 ---
 
 ## When to use
@@ -22,6 +22,7 @@ Read the specific rule files based on whether you are working on the Backend or
 - [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)

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

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

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

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

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

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

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

@@ -1,3 +1,10 @@
+---
+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.
@@ -21,14 +28,14 @@ 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();
+  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();
+  const stats = await Odac.DB.table('orders').count();
   console.log('Current orders:', stats);
 }).everyHour(1);
 ```

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

@@ -1,3 +1,10 @@
+---
+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.
@@ -9,13 +16,41 @@ High-performance database operations using the ODAC Query Builder.
 
 ## Patterns
 ```javascript
-const user = await Odac.Db.table('users')
+const user = await Odac.DB.table('users')
   .select('id', 'name', 'email')
   .where('status', 'active')
   .first();
 
-await Odac.Db.table('posts').insert({
+await Odac.DB.table('posts').insert({
   title: 'Hello',
   user_id: 1
 });
 ```
+
+## 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()`.
+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)