odac 1.3.0 → 1.4.1

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

@@ -0,0 +1,58 @@
+---
+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.
+
+## Architectural Approach
+Routes are defined in the `route/` directory. ODAC uses a two-phase routing strategy: O(1) exact matches followed by an indexed segment-based parametric lookup for maximum performance.
+
+## Core Rules
+1.  **Methods**: 
+    -   `Odac.Route.page(url, controller)`: For HTML views (GET).
+    -   `Odac.Route.get(url, controller)`: Targeted GET requests.
+    -   `Odac.Route.post(url, controller)`: Sensitive POST requests (CSRF enabled by default).
+2.  **Parameters**: Use `{id}` syntax for dynamic segments. Accessed via `Odac.request('id')`.
+3.  **Middlewares**: Chain logic using `.use('name')`. Global middlewares reside in `middleware/`.
+4.  **Error Handling**: Use `Odac.Route.error(code, controller)` for custom 404/500 pages.
+5.  **Auth Guard**: `Odac.Route.auth` automatically checks authentication before running the route.
+
+## Reference Patterns
+
+### 1. Standard Web Routes
+```javascript
+// page(path, controller)
+Odac.Route.page('/', 'Home'); 
+Odac.Route.page('/profile/{username}', 'User@profile');
+```
+
+### 2. Protected Routes & Middlewares
+```javascript
+// Only authenticated admins can see stats
+Odac.Route.auth
+  .use('is_admin')
+  .page('/admin/stats', 'Admin@stats');
+```
+
+### 3. Error Pages mapping
+```javascript
+Odac.Route.error(404, 'errors/NotFound');
+Odac.Route.error(500, 'errors/ServerError');
+```
+
+### 4. API Routes
+```javascript
+// Disable CSRF token check for external APIs
+Odac.Route.post('/api/webhook', 'Api@webhook', { token: false });
+```
+
+## Best Practices
+-   **Method Specification**: Use `.page()` for views to enable AJAX navigation compatibility.
+-   **Static First**: Prefer exact URL matches over parametric ones where possible (faster).
+-   **Controller Isolation**: Place error controllers in `controller/errors/` for better organization.
+-   **Parametric Safety**: Do not use too many nested dynamic segments in a single route.

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

@@ -0,0 +1,50 @@
+---
+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`.
+
+## Architectural Approach
+Storage is ideal for persistent data that requires sub-millisecond access and does not need the complexity of a relational database. It is shared across all processes and workers.
+
+## Core Rules
+1.  **Usage**: Access via `Odac.Storage`.
+2.  **Atomicity**: LMDB is ACID compliant and thread-safe.
+3.  **Data Types**: Supports strings, numbers, and JSON objects natively.
+4.  **Automatic Initialization**: The primary storage is initialized in the `storage/` directory automatically.
+
+## Reference Patterns
+
+### 1. Basic KV Operations
+```javascript
+// Setting data
+Odac.Storage.put('setting_theme', 'dark');
+Odac.Storage.put('app_data', { version: '1.0.0', last_check: Date.now() });
+
+// Getting data
+const theme = Odac.Storage.get('setting_theme');
+const appData = Odac.Storage.get('app_data');
+
+// Removing data
+Odac.Storage.remove('setting_theme');
+```
+
+### 2. Range Queries
+```javascript
+// Get all keys starting with 'pref:'
+const preferences = Odac.Storage.getRange({ start: 'pref:', end: 'pref:~' });
+for (const { key, value } of preferences) {
+  console.log(key, value);
+}
+```
+
+## Best Practices
+-   **Keyspacing**: Use prefixes like `sess:`, `cache:`, or `pref:` to organize your keys.
+-   **Performance**: Since it's memory-mapped, random reads are extremely fast (O(1)).
+-   **No Migrations**: Unlike SQL, Storage is schemaless. Ensure your code handles version changes in the stored JSON objects.
+-   **Avoid Large Blobs**: While it can store large values, keep them reasonable to maintain OS-level cache efficiency.

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

@@ -0,0 +1,41 @@
+---
+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).
+
+## Core Rules
+1.  **Usage**: Use `Odac.stream(callback)` to keep the connection open.
+2.  **Safety**: Always use `Odac.setInterval` and `Odac.setTimeout` inside streams; they are automatically cleaned up on disconnect.
+3.  **Return**: You must `return Odac.stream(...)` from the controller.
+
+## Reference Patterns
+### 1. Simple Stream
+```javascript
+module.exports = async (Odac) => {
+  return Odac.stream((send) => {
+    send({ status: 'connected' });
+    
+    Odac.setInterval(() => {
+      send({ time: Date.now() });
+    }, 1000);
+  });
+};
+```
+
+### 2. Async Generator Stream
+```javascript
+module.exports = async (Odac) => {
+  return Odac.stream(async function* () {
+    const logs = await getLogStream();
+    for await (const log of logs) {
+      yield log;
+    }
+  });
+};
+```

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

@@ -0,0 +1,64 @@
+---
+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.
+
+## Architectural Approach
+ODAC uses a request-scoped container. Most logic should be encapsulated in Service Classes (`class/`) which are automatically instantiated and attached to the `Odac` instance for every request.
+
+## Core Rules
+1.  **Directory Mapping**:
+    -   `route/`: URL definitions using `Odac.Route`.
+    -   `controller/`: Request handling logic (Input -> Response).
+    -   `class/`: Reusable business logic (Service Classes).
+    -   `view/`: HTML/Template files.
+    -   `middleware/`: Request interceptors.
+    -   `locale/`: Translation JSON files.
+2.  **Service Classes**:
+    -   Place classes in the `class/` directory.
+    -   They are automatically instantiated and attached to `Odac` as `Odac.ClassName`.
+    -   They are **Request Scoped** (new instance per request).
+3.  **Dependency Injection**: Services receive the framework instance (`Odac`) in their constructor.
+
+## Reference Patterns
+
+### 1. Defining a Service Class (Recommended)
+```javascript
+// class/User.js
+class User {
+  constructor(Odac) {
+    this.Odac = Odac;
+  }
+
+  async getProfile(id) {
+    // Access database or auth via this.Odac
+    return await this.Odac.DB.table('users').where('id', id).first();
+  }
+}
+module.exports = User;
+```
+
+### 2. Using a Service in a Controller
+```javascript
+// controller/User.js
+class User {
+  async show(Odac) {
+    // Service is automatically available as Odac.User
+    const profile = await Odac.User.getProfile(Odac.Request.input('id'));
+    
+    return Odac.View.make('user.profile', { profile });
+  }
+}
+module.exports = User;
+```
+
+## Best Practices
+-   **Context Awareness**: Use `this.Odac` inside service classes to access the specific request's state (current user, session, etc.).
+-   **Naming**: If a class name conflicts with core services (like `Mail`), it is placed under `Odac.App` (e.g., `Odac.App.Mail`).
+-   **Separation**: Keep controllers focused on request/response; move all data processing and business logic to the `class/` directory.

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

@@ -0,0 +1,49 @@
+---
+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.
+
+## Architectural Approach
+Translations are managed via JSON files in the `locale/` directory. The framework uses a flexible key-based system with support for placeholders.
+
+## Core Rules
+1.  **Storage**: Place translation files in `locale/` (e.g., `en.json`, `tr.json`).
+2.  **Tag Usage**: Use `<odac translate>Key</odac>` in views.
+3.  **Placeholders**: Use `%s1`, `%s2` in JSON and nested `<odac var="...">` tags in views.
+4.  **Backend Access**: Use `Odac.__(key, ...args)` in controllers.
+
+## Reference Patterns
+
+### 1. View Translations
+```html
+<!-- Simple -->
+<odac translate>Welcome</odac>
+
+<!-- With Placeholders -->
+<odac translate>Hello <odac var="user.name" /></odac>
+```
+
+### 2. Controller Translations
+```javascript
+const msg = Odac.__('Welcome back, %s1!', user.name);
+```
+
+### 3. Locale JSON Structure
+```json
+// locale/tr.json
+{
+  "Welcome": "Hoş Geldiniz",
+  "Hello %s1": "Merhaba %s1"
+}
+```
+
+## Best Practices
+-   **Descriptive Keys**: Use meaningful keys like `nav.home` or `form.error.required`.
+-   **Html Safety**: By default, translations are escaped. Use the `raw` attribute (`<odac translate raw>`) only for trusted HTML.
+-   **Language Selection**: Set the language at the start of a request via `Odac.Lang.setLanguage('tr')`.

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

@@ -0,0 +1,31 @@
+---
+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.
+
+## Core Rules
+1.  **Odac.Var**: A fluent interface for strings. Use it for `.slug()`, `.hash()`, `.is('email')`, and `.encrypt()`.
+2.  **Flow Control**:
+    -   `Odac.abort(code)`: Terminate request with HTTP status (e.g., 404, 403).
+    -   `Odac.direct(url)`: Redirect the user.
+    -   `Odac.session(key, value)`: Manage session data.
+
+## Reference Patterns
+### 1. Odac.Var (String Power)
+```javascript
+const slug = Odac.Var('My Post Title').slug();
+const isValid = Odac.Var('test@test.com').is('email');
+const password = Odac.Var('secret').hash(); // BCrypt
+```
+
+### 2. Redirect and Abort
+```javascript
+if (!user) return Odac.abort(404);
+if (!isLoggedIn) return Odac.direct('/login');
+```

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

@@ -0,0 +1,60 @@
+---
+name: backend-validation-skill
+description: Fluent ODAC validation strategies for input hardening, brute-force protection, and standardized error responses.
+metadata:
+  tags: backend, validation, fluent-api, input-security, brute-force, error-handling
+---
+
+# Backend Validation Skill
+
+The `Validator` service provides a fluent, chainable API for securing user input and enforcing business rules.
+
+## Architectural Approach
+Validation should happen as early as possible in the request lifecycle. The `Validator` service handles automatic error formatting and frontend integration.
+
+## 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`).
+
+## Reference Patterns
+
+### 1. Standard Validation Chaining
+```javascript
+module.exports = async function (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');
+
+  if (await validator.error()) {
+    return validator.result('Please fix input errors');
+  }
+
+  // Proceed with validated data
+  return validator.success('Success');
+};
+```
+
+### 2. Custom Variable and Security Validation
+```javascript
+validator.var('age', userAge).check('numeric|min:18').message('Must be 18+');
+
+// Security checks
+validator.post('bio').check('xss').message('Malicious HTML detected');
+validator.var('auth', null).check('usercheck').message('Authentication required');
+```
+
+### 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.
+
+## 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.

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

@@ -0,0 +1,68 @@
+---
+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.
+
+## Architectural Approach
+Views in ODAC are logic-light but powerful. They support automatic XSS protection, high-performance looping, and server-side JavaScript execution via `<script:odac>`.
+
+## Core Rules
+1.  **Skeleton Architecture**: Use `Odac.View.skeleton('name')` to wrap content in a layout.
+2.  **Data Binding**:
+    -   `{{ key }}`: Escaped output (Standard).
+    -   `{!! key !!}`: Raw output (Use with extreme caution).
+3.  **Conditionals**: Use `<odac:if condition="VAR"> ... </odac:if>`.
+4.  **Looping**: Use `<odac:for in="ARRAY" value="ITEM"> ... </odac:for>` or the performance-optimized `[[odac_for ...]]`.
+5.  **Server-Side JS**: Use `<script:odac>` for complex calculations during rendering.
+
+## Reference Patterns
+
+### 1. The Controller to View Flow
+```javascript
+// Controller
+Odac.View.skeleton('main');
+Odac.View.set({
+  title: 'Dashboard',
+  stats: { users: 150, orders: 45 }
+});
+```
+
+### 2. Template Syntax Reference
+```html
+<!-- Display Variable -->
+<h1>{{ title }}</h1>
+
+<!-- Conditional -->
+<odac:if condition="stats.users > 100">
+  <span class="badge">Popular!</span>
+</odac:if>
+
+<!-- Performance Loop -->
+[[odac_for user in users]]
+  <li>{{ user.name }}</li>
+[[odac_endfor]]
+```
+
+### 3. Backend JavaScript (`<script:odac>`)
+Perfect for calculations that shouldn't clutter the controller but are too complex for simple tags.
+```html
+<script:odac>
+  // Runs on the SERVER during rendering
+  const total = items.reduce((sum, i) => sum + i.price, 0);
+  const tax = total * 0.18;
+</script:odac>
+
+<p>Subtotal: ${{ total }}</p>
+<p>Tax: ${{ tax }}</p>
+```
+
+## Security Best Practices
+-   **Always use `{{ }}`**: Standard tags prevent XSS.
+-   **Limit `<script:odac>`**: Do not perform database queries or API calls inside views; keep them in the controller.
+-   **Partial Awareness**: Use `<odac:include view="path.to.view" />` for reusable components.

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

@@ -0,0 +1,73 @@
+---
+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.
+
+## Architectural Approach
+Frontend logic is organized into **Actions** using `Odac.action()`. This method centralizes event listeners, page-specific code, and lifecycle hooks.
+
+## Core Rules
+1.  **Centralization**: All frontend logic should be defined within `Odac.action({})`.
+2.  **Lifecycle Hooks**:
+    -   `start`: Fires once when the script initializes.
+    -   `load`: Fires after every page load (including AJAX navigations).
+3.  **Page Scoping**: Use the `page: { name: fn }` object to isolate code to specific routes.
+4.  **Persistent Storage**: Use `odac.storage(key, value)` for a secure LocalStorage wrapper.
+
+## Reference Patterns
+
+### 1. Global Lifecycle & Page Scoping
+```javascript
+Odac.action({
+  // Global - runs on every page
+  load: function() {
+    console.log('Page ready');
+  },
+
+  // Scoped - runs only on the 'dashboard' page
+  page: {
+    dashboard: function(vars) {
+      console.log('Welcome to Dashboard', vars);
+    }
+  }
+});
+```
+
+### 2. Event Handling
+```javascript
+Odac.action({
+  click: {
+    '#save-btn': function() {
+      alert('Saving...');
+    },
+    '.delete-item': 'fn.confirmDelete' // Reference a custom function
+  },
+  
+  fn: {
+    confirmDelete: function() {
+      return confirm('Are you sure?');
+    }
+  }
+});
+```
+
+### 3. Data Utilities
+```javascript
+// Accessing data shared from backend (Odac.share)
+const user = odac.data('user');
+
+// Using Storage wrapper
+odac.storage('theme', 'dark');
+const theme = odac.storage('theme');
+```
+
+## Best Practices
+-   **Clean Selectors**: Use ID or specific data-attributes for event listeners to avoid conflicts.
+-   **No Inline JS**: Move all logic from HTML attributes (onclick, etc.) into `Odac.action()`.
+-   **Shared State**: Use `odac.data()` to pass complex objects from the backend once per request.

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

@@ -0,0 +1,28 @@
+---
+name: frontend-forms-api-skill
+description: AJAX form and API request patterns in odac.js for interactive UX and predictable frontend data flows.
+metadata:
+  tags: frontend, forms, ajax, api-requests, odac-get, odac-post
+---
+
+# Frontend Forms & API Skill
+
+Handling AJAX form submissions and API requests.
+
+## 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()`.
+
+## 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);
+});
+```

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

@@ -0,0 +1,27 @@
+---
+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`.
+
+## Rules
+1.  **Selection**: Enable via `Odac.action({ navigate: 'main' })`.
+2.  **Exclusion**: Use `data-navigate="false"` or `.no-navigate` class for full reloads.
+3.  **Lifecycle**: Use `load` and `page` events to run code after navigation.
+
+## Patterns
+```javascript
+Odac.action({
+  navigate: {
+    update: 'main',
+    on: function(page, vars) {
+      console.log('Navigated to:', page);
+    }
+  }
+});
+```

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

@@ -0,0 +1,54 @@
+---
+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.
+
+## Architectural Approach
+ODAC prioritizes connection efficiency. `Odac.ws()` provides shared WebSocket connections across multiple browser tabs using `SharedWorker`, significantly reducing server load.
+
+## Core Rules
+1.  **Shared Connections**: Always prefer `Odac.ws(url, { shared: true })` for scalable real-time apps.
+2.  **Auto-Reconnect**: Enabled by default; the client handles network drops automatically.
+3.  **SSE (Streaming)**: Use `new EventSource(url)` for one-way streams (e.g., live logs, notifications).
+4.  **JSON Native**: Messages sent and received via `Odac.ws` are automatically parsed/stringified.
+
+## Reference Patterns
+
+### 1. Shared WebSocket (Cross-Tab)
+```javascript
+// One connection shared across all open tabs
+const ws = Odac.ws('/chat', { shared: true });
+
+ws.on('message', (data) => {
+  console.log('Update received in all tabs:', data);
+});
+
+// Sends message from current tab; others will receive the response
+ws.send({ type: 'chat', text: 'Hello World' });
+```
+
+### 2. Standard WebSocket (Per-Tab)
+```javascript
+const ws = Odac.ws('/game', { shared: false });
+ws.on('open', () => console.log('Game connected'));
+```
+
+### 3. Server-Sent Events (SSE)
+```javascript
+const source = new EventSource('/api/events');
+source.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  updateUI(data);
+};
+```
+
+## Best Practices
+-   **Resource Management**: Shared WebSocket automatically closes when the last tab using it is closed.
+-   **Fallback**: If `SharedWorker` is not supported (e.g., Safari), `Odac.ws` automatically falls back to a standard WebSocket.
+-   **Server-Side Hubs**: Ensure the backend uses `Odac.Hub` to send messages to the correct rooms or users.