odac 1.2.0 → 1.4.0

package/.agent/rules/memory.md

@@ -28,6 +28,21 @@ trigger: always_on
     - **Loop Optimization:** Use labeled loops (`label: for`) for efficient control flow in nested structures. Eliminate intermediate "flag" variables (`isMatch`, `found`) by using direct `return` or `continue label`.
     - **Direct Returns:** Return a value as soon as it is determined. Avoid assigning to a temporary variable (e.g. `matchedUser`) and breaking the loop, unless post-loop processing is strictly necessary.
     - **Async State Safety:** When an async function depends on mutable class state (like `pendingMiddlewares`), capture that state into a local `const` *synchronously* before triggering any async operations. This prevents race conditions where the state changes before the async task consumes it.
+    - **Async I/O Preference:** Prefer asynchronous file system operations (`fs.promises` or `await fs.promises.*`) over synchronous methods (`fs.readFileSync`, `fs.writeFileSync`) to prevent blocking the event loop and ensure high concurrency, especially in request handling paths.
 
 ## Dependency Management
-- **Prefer Native Fetch:** Use the native `fetch` API for network requests in both Node.js (18+) and browser environments to reduce dependencies and bundle size.
+- **Prefer Native Fetch:** Use the native `fetch` API for network requests in both Node.js (18+) and browser environments to reduce dependencies and bundle size.
+
+## 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.
+
+## 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.
+
+## 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`.
+
+## Security Logic & Authentication
+- **Enterprise Token Rotation:** The `Auth.js` system utilizes a non-blocking refresh token rotation mechanism for cookies (`odac_x`/`odac_y`). To prevent race conditions during concurrent requests in high-throughput SPAs, rotated tokens are **not** immediately deleted. Instead, their `active` timestamp is set to naturally expire in 60 seconds (Grace Period), and their `date` timestamp is set to the Unix Epoch (`new Date(0)`) as an identifier mark. Never delete rotated tokens immediately.

package/.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
     paths-ignore:
       - 'CHANGELOG.md'
       - 'package.json'
-      - '.github/workflows/test-publish.yml'
+      - '.github/workflows/**'
   workflow_dispatch:
 
 jobs:
@@ -41,10 +41,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npx semantic-release
-
-      - name: Publish to npm
-        run: npm publish --provenance --access public
-      
       - name: Get version
         id: version
         run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
@@ -56,6 +52,8 @@ jobs:
           repository: odac-run/actions
           token: ${{ secrets.GH_PAT }}
           path: .github/odac-actions
+          ref: main
+          persist-credentials: false
 
       - name: Generate Release Notes
         id: ai_notes
@@ -70,11 +68,35 @@ jobs:
       - name: Cleanup Actions
         if: always()
         run: rm -rf .github/odac-actions
+
+      - name: Update PR Title
+        uses: actions/github-script@v7
+        if: steps.ai_notes.outcome == 'success'
+        env:
+          AI_TITLE: ${{ steps.ai_notes.outputs.release-title }}
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const prs = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.sha,
+            });
+            if (prs.data.length > 0) {
+              await github.rest.pulls.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: prs.data[0].number,
+                title: process.env.AI_TITLE
+              });
+            }
+
       - name: Update Release
         uses: softprops/action-gh-release@v1
         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/.husky/pre-push

@@ -1,10 +1,10 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-# Prevent pushing code with High/Critical vulnerabilities
-echo "🛡️  Running Security Gate (npm audit)..."
+# Prevent pushing code with High/Critical vulnerabilities in production dependencies
+echo "🛡️  Running Production Security Gate (npm audit)..."
 
-npm audit --audit-level=high
+npm audit --audit-level=high --omit=dev
 
 if [ $? -ne 0 ]; then
     echo "❌ Security Check Failed! High vulnerabilities detected."

package/.releaserc.js

@@ -122,7 +122,7 @@ Powered by [⚡ ODAC](https://odac.run)
     [
       '@semantic-release/npm',
       {
-        npmPublish: false
+        provenance: true
       }
     ],
     [
@@ -134,4 +134,4 @@ Powered by [⚡ ODAC](https://odac.run)
     ],
     '@semantic-release/github'
   ]
-}
+}

package/AGENTS.md

@@ -0,0 +1,47 @@
+# ODAC Agent Instructions
+
+You are an AI Agent operating within the **ODAC Framework** repository. This document outlines the core principles, architectural standards, and operational guidelines you MUST follow to maintain the integrity and performance of this enterprise-grade system.
+
+## 1. Project Identity & Philosophy
+- **Name:** ODAC (Always uppercase in strings/docs/logs).
+- **Core Goal:** To provide a robust, zero-config, high-performance Node.js framework for distributed cloud applications.
+- **The "Big 3" Priorities:**
+    1. **Enterprise-Level Security:** Security is foundational. Default to secure, validate all inputs, sanitize all outputs.
+    2. **Zero-Config:** Works out-of-the-box. Convention over configuration.
+    3. **High Performance:** Optimize for throughput and low latency (Sub-millisecond targets).
+
+## 2. Architectural Principles
+- **Asynchronous & Non-Blocking:** Exclusively use non-blocking I/O. Use `fs.promises` instead of sync methods.
+- **Dependency Injection (DI):** Build components with DI for maximum testability.
+- **Single Responsibility Principle (SRP):** Keep classes and functions focused and small.
+- **Memory Management:** Be paranoid about leaks. Clean up listeners, streams, and connections.
+- **O(n log n) Bound:** Prioritize O(1) or O(n log n) algorithms. Justify any O(n²) operations.
+
+## 3. Coding Standards & Integrity
+- **Modern JavaScript:** Use ES6+ features, ES Modules (import/export). 
+- **Strictly Prohibited:** **No usage of `var`**. Use `const` (preferred) or `let`.
+- **Fail-Fast Pattern:** Implement early returns for negative cases. Avoid deeply nested `if/else`.
+- **Anti-Spaghetti Rules:**
+    - Resolve Promises upfront (e.g., `Promise.all`) before loops.
+    - Avoid mixing `await` inside deep logic.
+    - Capture mutable state synchronously before async operations.
+- **No Quick/Lazy Fixes:** Implement correctly from the start. Refactor if necessary; no "band-aid" patches.
+
+## 4. Technical Constraints (Strict Compliance)
+- **Session Safety:** `Odac.Request.setSession()` MUST be called before accessing `Odac.Request.session()`.
+- **Structured Logging:** No `console.log`. Use the internal JSON logger with appropriate levels.
+- **Native APIs:** Prefer native Node.js/Browser APIs (like `fetch`) over external libraries to minimize overhead.
+- **Token Rotation:** In `Auth.js`, use the 60-second grace period for rotated tokens. Never delete them immediately.
+- **Ajax Parsing:** `odac.js` must automatically parse JSON responses if headers allow.
+
+## 5. Testing & Documentation
+- **TDD Requirement:** No feature is complete without unit/integration tests covering both success and edge cases.
+- **Documentation:** Every exported member must have JSDoc explaining *Why* it exists, not just *What* it does.
+- **No User Dialogues in Code:** Do not include assistant-user interaction in comments or code files.
+
+## 6. Communication Style
+- **Authoritative & Precise:** Be the expert. Do not explain basic concepts.
+- **Proactive Correction:** If the user suggests a sub-optimal or insecure pattern (e.g., synchronous reads), refuse and implement the correct async version, explaining the trade-off.
+
+---
+*Note: This file is a living document. Updates should be reflected in `memory.md` and subsequent AI interactions.*

package/CHANGELOG.md

@@ -1,3 +1,67 @@
+### ⚙️ Engine Tuning
+
+- Extract MIME type definitions into a dedicated module.
+
+### ⚡️ Performance Upgrades
+
+- prevent redundant database table migration calls by introducing a static cache to track completed migrations.
+
+### ✨ What's New
+
+- add comprehensive ODAC Agent instructions and guidelines
+- **auth:** implement enterprise refresh token rotation with grace period and session persistence
+- Automatically parse JSON responses in client-side AJAX requests based on the `Content-Type` header.
+- implement comprehensive AI agent skills system and automated CLI setup
+
+### 🛠️ Fixes & Improvements
+
+- add HTML escaping functionality to Form class and corresponding tests
+- **ai:** correct target path for syncing AI skills
+- **auth:** replace magic number with constant for rotated token threshold
+- **auth:** replace magic number with constant for token rotation grace period
+- enhance odac:form parser with nested quotes and dynamic binding support
+- **route:** support nested property paths in actions and resolve App class conflict
+- **view:** ensure odac:for with 'in' attribute parses correctly as javascript
+- **view:** implement clear attribute in odac:form to control auto-clearing
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ⚙️ Engine Tuning
+
+- Improve disposable domain cache management by relocating the cache path, ensuring directory existence, and standardizing error logging.
+- Migrate file system operations in Mail and View to use async `fs.promises` for non-blocking I/O, aligning with new memory.md guidelines.
+- remove unused `WebSocketClient` variable assignments in `WebSocket.test.js`
+- streamline cache file reading by removing redundant access check.
+- **validator:** Migrate file operations to `fs.promises` for asynchronous I/O and enhance security with explicit content sanitization.
+
+### ⚡️ Performance Upgrades
+
+- Optimize parametric route matching by implementing a two-phase, pre-indexed lookup strategy grouped by segment count.
+
+### ✨ What's New
+
+- Add configurable max payload size and message rate limiting options to WebSocket routes.
+- Refined pre-push security audit to omit dev dependencies, optimized variable initializations, enhanced test mocks with `writeHead` and `finished` properties, introduced conditional `setTimeout` for request handling, and improved code formatting in client-side WebSocket and AJAX logic.
+- update `.gitignore` to no longer ignore package manager lock files and to ignore the `storage/` directory
+
+### 🛠️ Fixes & Improvements
+
+- Enhance route directory not found error logging and add ODAC casing convention to memory rules.
+- Set owner-only read/write permissions (0o600) for temporary cache files created during validation.
+- suppress tailwind process stdout output
+- Update default Unix socket path and enhance socket connection error handling with specific guidance for `ENOENT` errors.
+- Update Tailwind CSS watch flag to '--watch=always' and refine child process stdio configuration.
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### agent
 
 - Clarify logging strategies for development and production environments

package/README.md

@@ -10,7 +10,7 @@
 *   🔗 **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.
-*   🔐 **Authentication:** Ready-to-use session management, password hashing, and authentication helpers.
+*   🔐 **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.
 *   ⏰ **Task Scheduling:** Built-in Cron job system for handling background tasks and recurring operations.

package/bin/odac.js

@@ -16,6 +16,72 @@ const rl = readline.createInterface({
 
 const ask = question => new Promise(resolve => rl.question(question, answer => resolve(answer.trim())))
 
+/**
+ * Interactive selection menu for CLI.
+ * @param {string} title Menu title
+ * @param {string[]} options List of choice strings
+ * @returns {Promise<number>} Selected index
+ */
+const select = async (title, options) => {
+  if (!process.stdout.isTTY) return 0
+
+  return new Promise(resolve => {
+    let current = 0
+    const hideCursor = '\u001B[?25l'
+    const showCursor = '\u001B[?25h'
+
+    // Calculate total lines the title occupies
+    const titleLines = title.split('\n')
+    const totalLines = titleLines.length + options.length
+
+    const render = () => {
+      // Clear all lines we previously wrote
+      titleLines.forEach(line => {
+        process.stdout.write('\r\x1b[K' + line + '\n')
+      })
+      options.forEach((opt, i) => {
+        const line = i === current ? `\x1b[36m  ❯ ${opt}\x1b[0m` : `    ${opt}`
+        process.stdout.write('\r\x1b[K' + line + '\n')
+      })
+      process.stdout.write(`\x1b[${totalLines}A`) // Move back to the very start
+    }
+
+    process.stdout.write(hideCursor)
+    if (!process.stdin.isRaw) {
+      process.stdin.setRawMode(true)
+      process.stdin.resume()
+    }
+    readline.emitKeypressEvents(process.stdin)
+
+    render()
+
+    const onKey = (str, key) => {
+      if (key.name === 'up') {
+        current = current > 0 ? current - 1 : options.length - 1
+        render()
+      } else if (key.name === 'down') {
+        current = current < options.length - 1 ? current + 1 : 0
+        render()
+      } else if (key.name === 'return' || key.name === 'enter') {
+        cleanup()
+        process.stdout.write(`\x1b[${totalLines}B\n`) // Move down past everything
+        resolve(current)
+      } else if (key.ctrl && key.name === 'c') {
+        cleanup()
+        process.exit()
+      }
+    }
+
+    const cleanup = () => {
+      process.stdin.removeListener('keypress', onKey)
+      if (process.stdin.isRaw) process.stdin.setRawMode(false)
+      process.stdout.write(showCursor)
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}
+
 /**
  * Resolves Tailwind CSS paths and ensures required directories/files exist.
  * Supports multiple CSS entry points from 'view/css'.
@@ -73,6 +139,94 @@ function getTailwindConfigs() {
   return configs
 }
 
+/**
+ * Manages the AI Agent skills synchronization.
+ * @param {string} targetDir The directory to sync skills into.
+ */
+async function manageSkills(targetDir = process.cwd()) {
+  const aiSourceDir = path.resolve(__dirname, '../docs/ai')
+
+  if (!fs.existsSync(aiSourceDir)) {
+    console.error('❌ AI components not found in framework.')
+    return
+  }
+
+  const options = [
+    'Antigravity / Cascade (.agent/skills)',
+    'Claude / Projects (.claude/skills)',
+    'Continue (.continue/skills)',
+    'Cursor (.cursor/skills)',
+    'Kilo Code (.kilocode/skills)',
+    'Kiro CLI (.kiro/skills)',
+    'Qwen Code (.qwen/skills)',
+    'Windsurf (.windsurf/skills)',
+    'Custom Path',
+    'Skip / Cancel'
+  ]
+
+  const choiceIndex = await select('\n🤖 \x1b[36mODAC AI Agent Skills Manager\x1b[0m\nSelect your AI Agent / IDE for setup:', options)
+
+  let targetSubDir = ''
+  let copySkillsOnly = true
+
+  const SKIP_INDEX = 9
+  const CUSTOM_INDEX = 8
+
+  if (choiceIndex === SKIP_INDEX) return // Skip / Cancel
+
+  switch (choiceIndex) {
+    case 0:
+      targetSubDir = '.agent/skills'
+      break
+    case 1:
+      targetSubDir = '.claude/skills'
+      break
+    case 2:
+      targetSubDir = '.continue/skills'
+      break
+    case 3:
+      targetSubDir = '.cursor/skills'
+      break
+    case 4:
+      targetSubDir = '.kilocode/skills'
+      break
+    case 5:
+      targetSubDir = '.kiro/skills'
+      break
+    case 6:
+      targetSubDir = '.qwen/skills'
+      break
+    case 7:
+      targetSubDir = '.windsurf/skills'
+      break
+    case CUSTOM_INDEX:
+      targetSubDir = await ask('Enter custom path: ')
+      copySkillsOnly = false
+      break
+    default:
+      return
+  }
+
+  const targetBase = path.resolve(targetDir, targetSubDir)
+  const targetPath = targetBase
+
+  try {
+    fs.mkdirSync(targetPath, {recursive: true})
+
+    if (copySkillsOnly) {
+      const skillsSource = path.join(aiSourceDir, 'skills')
+      fs.cpSync(skillsSource, targetPath, {recursive: true})
+    } else {
+      fs.cpSync(aiSourceDir, targetPath, {recursive: true})
+    }
+
+    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${targetSubDir}\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)
+  }
+}
+
 async function run() {
   if (command === 'init') {
     const projectName = args[0] || '.'
@@ -110,13 +264,27 @@ async function run() {
       }
 
       console.log('\n✨ Project initialized successfully!')
+
+      // Interactive AI Skills setup
+      if (process.stdout.isTTY) {
+        const setupAIIndex = await select('\n🤖 Should we setup AI Agent skills for your IDE?', ['Yes', 'No'])
+        if (setupAIIndex === 0) {
+          await manageSkills(targetDir)
+        } else {
+          console.log('\n💡 \x1b[33mTip:\x1b[0m You can always run \x1b[36mnpx odac skills\x1b[0m later.')
+        }
+      }
     } catch (error) {
       console.error('❌ Error initializing project:', error.message)
     }
   } else if (command === 'dev') {
+    // ... existing dev logic ...
     if (cluster.isPrimary) {
       const configs = getTailwindConfigs()
       const tails = []
+      const names = configs.map(c => c.name).join(', ')
+
+      console.log(`🎨 \x1b[36mODAC Styles:\x1b[0m Watching for changes (${names})`)
 
       configs.forEach(({input, cssOutput, name, isCustom}) => {
         let tailwindProcess = null
@@ -125,19 +293,28 @@ async function run() {
           const localCli = path.join(process.cwd(), 'node_modules', '.bin', 'tailwindcss')
           const useLocal = fs.existsSync(localCli)
           const cmd = useLocal ? localCli : 'npx'
-          const args = useLocal ? ['-i', input, '-o', cssOutput, '--watch'] : ['@tailwindcss/cli', '-i', input, '-o', cssOutput, '--watch']
-
-          console.log(`🎨 Starting Tailwind CSS for ${name} (${isCustom ? 'Custom' : 'Default'})...`)
-          console.log(`📂 Watching directory: ${process.cwd()}`)
+          const args = useLocal
+            ? ['-i', input, '-o', cssOutput, '--watch=always']
+            : ['@tailwindcss/cli', '-i', input, '-o', cssOutput, '--watch=always']
 
           tailwindProcess = spawn(cmd, args, {
-            stdio: 'inherit',
-            shell: !useLocal, // Valid for npm/npx compatibility if local not found
+            stdio: ['pipe', 'ignore', 'pipe'],
+            shell: !useLocal,
             cwd: process.cwd()
           })
 
+          tailwindProcess.stderr.on('data', chunk => {
+            const raw = chunk.toString()
+            const lines = raw.split('\n')
+            for (const line of lines) {
+              const clean = line.replace(/\x1B\[[0-9;]*[JKmsu]/g, '').trim()
+              if (!clean || clean.startsWith('Done in') || clean.startsWith('≈')) continue
+              process.stderr.write(`\x1b[31m[ODAC Style Error]\x1b[0m ${line}\n`)
+            }
+          })
+
           tailwindProcess.on('error', err => {
-            console.error(`❌ Tailwind watcher failed to start for ${name}:`, err.message)
+            console.error(`❌ \x1b[31m[ODAC Style Error]\x1b[0m Failed to start watcher for ${name}:`, err.message)
           })
 
           tailwindProcess.on('exit', code => {
@@ -150,7 +327,6 @@ async function run() {
 
         startWatcher()
 
-        // Push a wrapper compatible with the cleanup function
         tails.push({
           kill: () => {
             if (tailwindProcess) tailwindProcess.kill()
@@ -198,6 +374,8 @@ async function run() {
   } else if (command === 'start') {
     process.env.NODE_ENV = 'production'
     require('../index.js')
+  } else if (command === 'skills') {
+    await manageSkills()
   } else {
     console.log('Usage:')
     console.log('  npx odac init            (Interactive mode)')
@@ -205,6 +383,7 @@ async function run() {
     console.log('  npx odac dev             (Development mode)')
     console.log('  npx odac build           (Production build)')
     console.log('  npx odac start           (Start server)')
+    console.log('  npx odac skills          (Sync AI Agent skills)')
   }
 
   rl.close()