odac 1.1.0 → 1.3.0

package/.agent/rules/coding.md

@@ -0,0 +1,27 @@
+---
+trigger: always_on
+---
+
+# Coding Standards & Best Practices
+
+## 1. Testing Strategy
+- **Rule:** No feature is complete without tests.
+- **Goal:** Maintain stability and prevent regressions.
+- **Action:** Write unit tests for logic and integration tests for API endpoints.
+
+## 2. Dependency Management
+- **Philosophy:** "Less is more."
+- **Rule:** Avoid external dependencies unless absolutely necessary.
+- **Preference:** Prioritize native Node.js modules (`fs`, `http`, `crypto`, etc.) to reduce bundle size and security attack surface.
+
+## 3. Error Handling
+- **Rule:** Fail loudly and clearly.
+- **Practice:** Use custom Error classes where possible.
+- **Message:** Error messages should guide the developer on how to fix the issue, not just say "Error".
+
+## 4. Modern JavaScript
+- **Standard:** Use ES6+ features (Async/Await, Arrow functions, Destructuring).
+- **Modules:** Strict adherence to ES Modules (import/export).
+
+## 5. Route & Session Logic
+- **Session Initialization:** `Odac.Request.setSession()` MUST be called before any logic that attempts to access `Odac.Request.session()`. This includes global middleware or form processing logic in `Route.js` that runs before the specific controller is resolved.

package/.agent/rules/memory.md

@@ -0,0 +1,42 @@
+---
+trigger: always_on
+---
+
+# Project Memory & Rules
+
+## Configuration & Environment
+- **Debug Mode Logic:** The `debug` configuration in `src/Config.js` defaults to `process.env.NODE_ENV !== 'production'`. This ensures that `odac dev` (undefined NODE_ENV) enables debug/hot-reload, while `odac start` (NODE_ENV=production) disables it to use caching.
+- **Logging Strategy:** 
+    - **Development (`debug: true`):** Enable verbose logging, hot-reloading notifications, and detailed stack traces for easier debugging.
+    - **Production (`debug: false`):** Minimize logging to essential operational events (Start/Stop) and Fatal Errors only. Avoid `console.log` for per-request information to preserve performance and disk space. Sensitive error details must not be exposed to the user.
+
+## Development Standards & Integrity
+- **NO QUICK/LAZY FIXES:** Explicitly prohibited. 
+    - Never implement truncated solutions (e.g., `substring(0, 32)` on a hash) or temporary workarounds just to make code run.
+    - Always implement the mathematically and architecturally correct "Enterprise-Grade" solution (e.g., using raw `Buffer` for crypto keys instead of hex strings).
+    - If a proper solution requires refactoring, do the refactoring. Do not patch holes.
+    - **Prioritize Correctness over Speed:** It is better to verify documentation or think for a minute than to output a sub-par patch.
+
+## Code Quality & Modern Standards
+- **No Legacy Syntax:** 
+    - **Strictly Prohibited:** The use of `var` is forbidden. Use `const` (preferred) or `let` (only if mutation is needed).
+    - **Variable Scope:** Ensure variables are block-scoped to prevent leakage.
+- **Anti-Spaghetti Code:**
+    - **Fail-Fast Pattern:** Avoid deeply nested `if/else` logic. Use early returns (`return`, `break`, `continue`) to handle negative cases immediately.
+    - **Promise Handling:** Resolve Promises upfront (e.g., `Promise.all` or strict `await` before loops) rather than mixing `await` inside deep logic or mutating input objects.
+    - **Strict Equality:** Always use strict equality checks (`===`) instead of loose ones.
+    - **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.
+
+## 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.

package/.agent/rules/project.md

@@ -0,0 +1,30 @@
+---
+trigger: always_on
+---
+
+# Project Context & Design Philosophy
+
+## Project Identity
+- **Type:** Node.js Framework
+- **Goal:** To provide a robust, enterprise-ready backbone for web applications.
+
+## Core Priorities (The "Big 3")
+1.  **Enterprise-Level Security:** 
+    - Security is not an afterthought; it is foundational. 
+    - Default to secure settings. 
+    - Validate all inputs. 
+    - Sanitize outputs. 
+    - Use established cryptographic standards.
+2.  **Zero-Config:** 
+    - The framework should work "out of the box" with sensible defaults. 
+    - Configuration should be optional, not mandatory for getting started. 
+    - "Convention over Configuration" is key.
+3.  **High Performance:** 
+    - Code must be optimized for throughput and low latency. 
+    - Avoid unnecessary overhead. 
+    - Profile and benchmark critical paths. 
+    - Memory management is crucial.
+
+## Interaction Guidelines for AI
+- Always assume the user wants the most efficient and secure solution unless specified otherwise.
+- When suggesting architecture, prioritize scalability and maintainability.

package/.agent/rules/workflow.md

@@ -0,0 +1,16 @@
+---
+trigger: always_on
+---
+
+# Development Workflow Rules
+
+## 1. Quality Assurance (Linting)
+- **Rule:** **ALWAYS** runs lint checks after writing or modifying code.
+- **Action:** Execute the project's linting command (e.g., `npm run lint` or `eslint .`) to verify code compliance.
+- **Strictness:** Do not mark a task as complete if lint errors persist. Fix them immediately.
+
+## 2. Documentation Hygiene
+- **Rule:** Documentation must be kept in sync with code changes.
+- **Trigger:** Adding a new feature, modifying an API, or changing configuration behavior.
+- **Action:** Update the relevant `.md` files (README, API docs, etc.) or JSDoc comments.
+- **Goal:** Ensure that the documentation is never stale and accurately reflects the current state of the codebase.

package/.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
     paths-ignore:
       - 'CHANGELOG.md'
       - 'package.json'
+      - '.github/workflows/**'
   workflow_dispatch:
 
 jobs:
@@ -27,9 +28,12 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Update npm
+        run: npm install -g npm@latest
+
       - name: Install dependencies
         run: npm install
 
@@ -37,3 +41,66 @@ 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
+
+      - name: Checkout Actions
+        if: steps.version.outputs.version != ''
+        uses: actions/checkout@v4
+        with:
+          repository: odac-run/actions
+          token: ${{ secrets.GH_PAT }}
+          path: .github/odac-actions
+          ref: main
+          persist-credentials: false
+
+      - name: Generate Release Notes
+        id: ai_notes
+        if: steps.version.outputs.version != ''
+        uses: ./.github/odac-actions/actions/release-notes
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          michelangelo: ${{ secrets.MICHELANGELO }}
+        timeout-minutes: 15
+        continue-on-error: true
+
+      - 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/.github/workflows/test-coverage.yml

@@ -20,7 +20,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: 22.x
+        node-version: [18.x, 24.x]
 
     steps:
       - name: Checkout code
@@ -41,19 +41,20 @@ jobs:
         run: npm test
 
       - name: Upload coverage reports
-        if: matrix.node-version == '22.x'
-        uses: codecov/codecov-action@v3
+        if: matrix.node-version == '18.x'
+        uses: codecov/codecov-action@v4
         with:
           files: ./coverage/lcov.info
           flags: unittests
           name: codecov-umbrella
           fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Coverage Summary
-        if: matrix.node-version == '22.x'
+        if: matrix.node-version == '18.x'
         run: |
           echo "## Test Coverage Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
-          npx nyc report --reporter=text-summary >> $GITHUB_STEP_SUMMARY || echo "Coverage report not available" >> $GITHUB_STEP_SUMMARY
+          npx nyc report --reporter=text-summary --temp-directory=coverage >> $GITHUB_STEP_SUMMARY || echo "Coverage report not available" >> $GITHUB_STEP_SUMMARY
           echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

package/.husky/pre-commit

@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "🔍 Running Pre-commit Hooks..."
+
+# Run linting and formatting on staged files
+npx lint-staged
+
+# Run tests for changed files to ensure no regressions
+node test/scripts/check-coverage.js

package/.husky/pre-push

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

package/.releaserc.js

@@ -129,7 +129,7 @@ Powered by [⚡ ODAC](https://odac.run)
       '@semantic-release/git',
       {
         assets: ['package.json', 'CHANGELOG.md'],
-        message: '⚡ ODAC v${nextRelease.version} Released'
+        message: '⚡ ODAC.JS v${nextRelease.version} Released'
       }
     ],
     '@semantic-release/github'

package/CHANGELOG.md

@@ -1,3 +1,102 @@
+### ⚙️ 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
+
+### deps
+
+- update `tar` override version and add `@semantic-release/npm` override.
+
+### ⚙️ Engine Tuning
+
+- add JSDoc and default parameter to `Auth.user` method for improved clarity and robustness.
+- enable method chaining for cron job condition definitions
+- Enhance cryptographic security by using CSPRNG for token generation, SHA-256 for encryption key derivation, and adding clarifying configuration comments.
+- Improve authentication logic by adopting fail-fast patterns, upfront promise resolution, and optimized loop control, aligning with new code quality guidelines.
+- Improve view file reading by using `fsPromises.open` for better resource management and atomic operations.
+- Migrate route and middleware loading to asynchronous file system operations for improved performance.
+- Remove redundant `fs.existsSync` checks before `fs.mkdirSync` and add `EEXIST` handling for `fs.writeFileSync`.
+- remove unused nodeCrypto import from Config.test.js
+- rename config.json to odac.json for brand consistency
+- Streamline default CSS file creation using `fs.writeFileSync` 'wx' flag.
+- Use raw Buffer for encryption key hashing, aligning with enterprise-grade development standards.
+
+### ⚡️ Performance Upgrades
+
+- Implement enterprise-grade HTTP server performance configurations
+- Optimize file serving by eliminating redundant `fs.stat` calls and deriving content length directly from the read file.
+- **route:** implementation of async I/O and metadata caching for static assets
+- **view:** switch to async I/O and implement aggressive production caching
+
+### ✨ What's New
+
+- add built-in tailwindcss v4 support with zero-config
+- Enhance cron job scheduling with new `.at()` and `.raw()` methods, update cron documentation.
+- Enhance Tailwind CSS watcher to prioritize local CLI over npx for improved reliability and adjust shell option accordingly.
+- **framework:** add Odac.session() helper and update docs
+- implement Class-Based Controllers support and update docs
+- Implement conditional environment variable loading, configure server workers based on debug mode
+- Replaced bcrypt with native Node.js crypto.scrypt for hashing, removed bcrypt and axios dependencies, and updated related validation checks.
+- support multiple Tailwind CSS entry points in build and dev processes.
+
+### 📚 Documentation
+
+- add documentation for multiple CSS file support
+- add project structure overview to README
+- Add Tailwind CSS v4 integration to README features list
+- Introduce architectural and cluster safety notes to Token, Ipc, and Storage modules.
+
+### 🛠️ Fixes & Improvements
+
+- Add null safety checks for `odac.Request` and its `header` method when determining the default language.
+- add options support to authenticated routes (GET/POST)
+- Conditionally initialize Odac request-dependent components and provide a dedicated Odac instance with cleanup to cron jobs.
+- Enhance server port configuration to prioritize command-line arguments and environment variables
+- Initialize session in Route.js during form processing to ensure proper session availability before access, aligning with new coding standards.
+- **package:** resolve high severity npm vulnerabilities
+- Prevent form token expiration errors by dynamically generating forms at runtime.
+- Prevent middleware race conditions by synchronously capturing state and improve Tailwind CSS watcher robustness with auto-restart.
+- Refine error message styling in form validation
+- Replace insecure token generation with cryptographically secure random bytes for `token_x` and `token_y`.
+- **session:** change cookie SameSite policy to Lax for OAuth support
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
 ### Fix
 
 - Resolve WebSocket handshake error by echoing subprotocol header

package/README.md

@@ -6,6 +6,7 @@
 ## ✨ Key Features
 
 *   🚀 **Developer Friendly:** Simple setup and intuitive API design let you start building immediately.
+*   🎨 **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.
@@ -13,6 +14,7 @@
 *   🗄️ **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.
+*   ⚡ **Zero-Config Early Hints:** Intelligent HTTP 103 implementation that requires **no setup**. ODAC automatically analyzes your views and serves assets instantly, drastically improving load times without a single line of code.
 
 ## 🛠️ Advanced Capabilities
 
@@ -51,6 +53,20 @@ cd my-app
 npm run dev
 ```
 
+## 📂 Project Structure
+
+```
+project/
+├── class/          # Business logic classes
+├── controller/     # HTTP request handlers
+├── middleware/     # Route middlewares
+├── public/         # Static assets
+├── route/          # Route definitions
+├── view/           # HTML templates
+├── .env            # Environment variables
+└── odac.json       # App configuration
+```
+
 ## 📚 Documentation
 
 For detailed guides, API references, and examples, visit our [official documentation](https://docs.odac.run).