odac 0.9.0

package/.editorconfig

@@ -0,0 +1,21 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.js]
+quote_type = single
+
+[*.json]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/workflows/auto-pr-description.yml

@@ -0,0 +1,49 @@
+name: Auto-generate PR Description
+
+on:
+  pull_request:
+    types: [opened]
+    branches:
+      - main
+
+jobs:
+  update-pr-description:
+    runs-on: ubuntu-latest
+    # Only run for PRs from `dev` to `main`
+    if: github.head_ref == 'dev' && github.base_ref == 'main'
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Fetch all history for all branches and tags to get the commit messages
+          fetch-depth: 0
+
+      - name: Generate PR Body
+        id: generate_body
+        run: |
+          # Get commit messages from the PR's commits
+          COMMITS=$(git log origin/${{ github.base_ref }}..origin/${{ github.head_ref }} --pretty=format:"* %s")
+          # Set the multiline output for the next step
+          {
+            echo 'body<<EOF'
+            echo "This PR includes the following changes:"
+            echo ""
+            echo "$COMMITS"
+            echo 'EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Update PR Title and Body
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.rest.pulls.update({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+              title: 'Sync `dev` to `main`',
+              body: `${{ steps.generate_body.outputs.body }}`
+            });

package/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+          - 'CHANGELOG.md'
+          - 'package.json'
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'CandyPack v') || github.event_name == 'workflow_dispatch'"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - name: Install dependencies
+        run: npm install
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/test-coverage.yml

@@ -0,0 +1,58 @@
+name: Test Coverage
+
+on:
+  push:
+    branches: [main, dev]
+    paths:
+      - '**/*.js'
+      - 'package.json'
+      - 'jest.config.js'
+  pull_request:
+    branches: [main, dev]
+    paths:
+      - '**/*.js'
+      - 'package.json'
+      - 'jest.config.js'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 22.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests with coverage
+        run: npm test
+
+      - name: Upload coverage reports
+        if: matrix.node-version == '18.x'
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false
+
+      - name: Comment PR with coverage
+        if: github.event_name == 'pull_request' && matrix.node-version == '18.x'
+        uses: romeovs/lcov-reporter-action@v0.3.1
+        with:
+          lcov-file: ./coverage/lcov.info
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          delete-old-comments: true

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+npx lint-staged
+node test/scripts/check-coverage.js

package/.kiro/steering/code-style.md

@@ -0,0 +1,56 @@
+---
+inclusion: always
+---
+
+# Code Style Guidelines
+
+## Comments
+
+- **Language**: All code comments MUST be written in English
+- **Minimalism**: Avoid unnecessary comments - write self-documenting code instead
+- **When to comment**: Only add comments when the code's intent is not immediately clear from the code itself
+- **What not to comment**: 
+  - Obvious operations (e.g., `// Set variable` before `x = 5`)
+  - Code that explains itself through clear naming
+  - Redundant descriptions of what the code does
+
+## Examples
+
+### Bad (unnecessary comments):
+```javascript
+// Get user email
+const email = user.email
+
+// Loop through items
+for (const item of items) {
+  // Process item
+  processItem(item)
+}
+```
+
+### Good (self-documenting):
+```javascript
+const email = user.email
+
+for (const item of items) {
+  processItem(item)
+}
+```
+
+### Good (necessary comment):
+```javascript
+// ACME protocol requires 30-second delay between retries
+await sleep(30000)
+
+// Workaround for MySQL connection pool bug in v2.3.0
+if (connection.threadId === null) {
+  connection = await reconnect()
+}
+```
+
+## General Principles
+
+- Let the code speak for itself through clear variable and function names
+- Use comments sparingly to explain "why" not "what"
+- Keep comments concise and to the point
+- Update or remove comments when code changes

package/.kiro/steering/product.md

@@ -0,0 +1,20 @@
+# CandyPack Product Overview
+
+CandyPack is a next-generation server and framework toolkit that combines hosting infrastructure with a web development framework. It's designed as a lightweight, zero-config solution for building and deploying modern web applications.
+
+## Core Components
+
+- **Server**: Full-featured hosting platform with DNS, SSL, mail server (IMAP/SMTP), and multi-domain support
+- **Backend**: Web application framework with routing, authentication, CSRF protection, and internationalization
+- **Frontend**: Client-side framework (candy.js) with AJAX navigation, form handling, and API requests
+- **CLI**: Command-line interface for server management and deployment
+- **Watchdog**: Process monitoring and management system
+
+## Key Philosophy
+
+- **Developer-first**: Zero-config approach, focus on code rather than infrastructure
+- **Performance-oriented**: Lightweight and optimized for speed
+- **Security-focused**: Built-in CSRF protection, SSL automation, secure defaults
+- **Global-ready**: Multi-language support and internationalization built-in
+
+The project follows AGPL-3.0 licensing and targets Node.js 18+ environments.

package/.kiro/steering/structure.md

@@ -0,0 +1,77 @@
+# Project Structure & Architecture
+
+## Directory Organization
+
+```
+├── bin/              # Executable binaries (candy, candypack)
+├── cli/              # Command-line interface
+│   └── src/          # CLI implementation (Cli.js, Connector.js, Monitor.js)
+├── core/             # Core dependency injection system
+├── framework/        # Web framework implementation
+│   ├── src/          # Framework modules (Auth, Route, Server, etc.)
+│   └── web/          # Client-side JavaScript (candy.js)
+├── server/           # Server infrastructure
+│   └── src/          # Server modules (DNS, SSL, Mail, Web, etc.)
+├── watchdog/         # Process monitoring system
+├── web/              # Template website (copied when creating new sites)
+│   ├── controller/   # Template controllers
+│   ├── package.json  # Template package.json with {{domain}} placeholders
+│   └── config.json   # Template configuration
+├── docs/             # Documentation (backend, frontend & server)
+│   ├── index.json    # Documentation navigation structure
+│   ├── backend/      # Backend documentation files
+│   ├── frontend/     # Frontend documentation files
+│   └── server/       # Server documentation files
+├── locale/           # Internationalization files
+└── test/             # Jest test files
+```
+
+## Architecture Patterns
+
+### Dependency Injection (Core)
+
+- **Global Candy**: Singleton registry pattern via `global.Candy`
+- **Module Loading**: Dynamic require with `core()`, `cli()`, `server()`, `watchdog()` methods
+- **Singleton Management**: Automatic instantiation and caching
+
+### Framework Pattern
+
+- **Request Lifecycle**: Each request gets a fresh Candy instance with req/res context
+- **Controller Pattern**: Simple function exports in `controller/` directories
+- **Helper Functions**: Global shortcuts (`__()`, `abort()`, `return()`, etc.)
+
+### File Naming Conventions
+
+- **PascalCase**: Class files and main modules (e.g., `Candy.js`, `Server.js`)
+- **camelCase**: Utility functions and instances
+- **lowercase**: Entry points (`index.js`)
+
+### Module Structure
+
+- Each module can have an optional `init()` method for setup
+- Framework modules receive Candy instance for request context
+- Server modules are typically singletons for infrastructure
+
+### Web Template System
+
+- **Template Directory**: `web/` serves as the template for new websites
+- **Automatic Copying**: When creating a new site, entire `web/` directory is copied
+- **Template Variables**: Files can contain placeholders like `{{domain}}` and `{{domain_original}}`
+- **Post-Processing**: After copying, template variables are replaced with actual values
+- **Template Files**:
+  - `package.json` - Contains domain placeholders for name and description
+  - `config.json` - Basic routing configuration
+  - `controller/` - Example controller implementations
+
+### Documentation System
+
+- **Index File**: `docs/index.json` contains the navigation structure for all documentation
+- **Adding New Docs**: When creating new documentation files, they MUST be added to `docs/index.json`
+- **Language**: All documentation content must be written in English
+- **Structure**: Documentation is organized into THREE sections only:
+  - `docs/server/` - Server infrastructure documentation (CLI, DNS, SSL, Mail)
+  - `docs/backend/` - Backend framework documentation (Controllers, Routing, Auth, Database)
+  - `docs/frontend/` - Frontend documentation (candy.js, AJAX navigation, Forms)
+- **IMPORTANT**: There is NO `docs/framework/` directory - backend docs go in `docs/backend/`
+- **File Organization**: Each section has folders with numbered prefixes (01-overview, 02-structure, etc.)
+- **Navigation**: The index.json file defines the title and hierarchy shown in documentation site

package/.kiro/steering/tech.md

@@ -0,0 +1,87 @@
+# Technology Stack & Build System
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+ (required)
+- **Language**: JavaScript (ES6+, CommonJS modules)
+- **Database**: MySQL2, SQLite3 support
+- **Security**: bcrypt, node-forge, ACME client for SSL
+- **Mail**: Built-in SMTP/IMAP server with DKIM signing
+- **Proxy**: HTTP proxy for multi-domain hosting
+- **DNS**: Native DNS server implementation
+
+## Code Quality Tools
+
+- **Linting**: ESLint with Prettier integration
+- **Testing**: Jest with coverage reporting (no threshold enforcement)
+- **Git Hooks**: Husky with pre-commit linting and test execution
+- **Release**: Semantic Release with conventional commits
+- **Test Check**: Automatic test execution on commit for changed files (pass/fail only)
+
+## Common Commands
+
+```bash
+# Development
+npm run lint          # Run ESLint
+npm run lint:fix      # Fix linting issues automatically
+npm test              # Run Jest tests with coverage
+npm run test:watch    # Run tests in watch mode
+
+# Release
+npm run release       # Semantic release (automated)
+
+# Installation
+curl -sL https://candypack.dev/install | bash  # Quick install
+npm install -g candypack                       # Manual install
+
+# Git Hooks & CI/CD
+# Pre-commit automatically runs:
+# 1. lint-staged (ESLint + Prettier on staged files)
+# 2. Test execution for changed core/ and server/ files (test/scripts/check-coverage.js)
+# Note: Coverage is tracked but doesn't block commits - focus is on test pass/fail
+
+# GitHub Actions (on PR to main/dev):
+# 1. Runs all tests with coverage
+# 2. Runs linter
+# 3. Tests on Node.js 18.x and 22.x
+# 4. Uploads coverage to Codecov
+# 5. Comments PR with coverage report
+```
+
+## Code Style
+
+- **Prettier Config**: No semicolons, single quotes, 140 char width, 2-space tabs
+- **ESLint**: Separate configs for server/framework/web/browser contexts
+- **Globals**: `Candy` and `__` are global variables across the codebase
+- **Module System**: CommonJS (`require`/`module.exports`) for server-side code
+
+## Logging Standards
+
+### Server & Core Modules
+- **Log Class**: Use `Candy.core('Log', false).init('ModuleName')` for all logging in `server/` and `core/` directories
+- **Usage Pattern**:
+
+  ```javascript
+  const {log, error} = Candy.core('Log', false).init('ModuleName')
+
+  log('Info message')
+  log('Message with %s placeholder', 'value')
+  error('Error message', errorObject)
+  ```
+
+- **CLI Mode**: Logs are automatically suppressed in CLI mode to avoid breaking the interface
+- **Location**: Log class is in `core/Log.js` (also available via `server/src/Log.js` for backward compatibility)
+
+### Framework Modules
+- **Console Logging**: Use `console.log()` and `console.error()` directly in `framework/` directory
+- **Reason**: Framework runs in user's application context where Log class may not be available
+- **Usage Pattern**:
+
+  ```javascript
+  console.log('[ModuleName] Info message')
+  console.error('[ModuleName] Error:', error.message)
+  ```
+
+### General Rule
+- **Server/Core**: Always use Log class (never `console.log`)
+- **Framework**: Always use `console.log` (Log class not guaranteed to be available)

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 140,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "arrowParens": "avoid",
+  "bracketSpacing": false,
+  "endOfLine": "lf"
+}

package/.releaserc.js

@@ -0,0 +1,134 @@
+module.exports = {
+  branches: ['main'],
+  plugins: [
+    [
+      '@semantic-release/commit-analyzer',
+      {
+        preset: 'conventionalcommits'
+      }
+    ],
+    [
+      '@semantic-release/release-notes-generator',
+      {
+        preset: 'conventionalcommits',
+        writerOpts: {
+          transform: (c, context) => {
+            const commit = JSON.parse(JSON.stringify(c))
+
+            const map = {
+              feat: "✨ What's New",
+              fix: '🛠️ Fixes & Improvements',
+              perf: '⚡️ Performance Upgrades',
+              refactor: '⚙️ Engine Tuning',
+              docs: '📚 Documentation',
+              style: '🎨 Style',
+              test: '✅ Tests',
+              chore: '🔧 Maintenance & Cleanup',
+              build: '🏗️ Build',
+              ci: '🤖 CI'
+            }
+
+            commit.type = map[commit.type] || commit.type
+
+            const hide = ['🎨 Style', '🔧 Maintenance & Cleanup', '🏗️ Build', '🤖 CI', '✅ Tests']
+            if (!commit.type || hide.includes(commit.type)) return false
+
+            if (commit.scope === '*' || commit.scope === 'root') commit.scope = ''
+
+            if (commit.notes) {
+              commit.notes.forEach(n => {
+                n.title = '💥 BREAKING CHANGES'
+              })
+            }
+
+            if (commit.subject) {
+              // Find and extract PR number from the subject, e.g., "feat: new thing (#123)"
+              const prRegex = /\s\(#(\d+)\)$/
+              const prMatch = commit.subject.match(prRegex)
+              const prNumber = prMatch ? prMatch[1] : null
+
+              // If a PR number is found, remove it from the subject to avoid it appearing twice
+              if (prNumber) {
+                commit.subject = commit.subject.replace(prRegex, '')
+              }
+
+              let prLink = ''
+
+              // Get author name - prefer GitHub login if available
+              const email = commit.committer.email || commit.authorEmail || ''
+              const ghUserMatch = email.match(/^(?:\d+\+)?([a-zA-Z0-9-]+)@users\.noreply\.github\.com$/)
+              const ghUser = ghUserMatch ? ghUserMatch[1] : null
+
+              let attribution = ''
+              if (ghUser) attribution = `by @${ghUser}`
+
+              // Get PR link if a number was found
+              if (prNumber && context.host && context.owner && context.repository) {
+                const prUrl = `https://${context.host}/${context.owner}/${context.repository}/pull/${prNumber}`
+                const prLink = `[#${prNumber}](${prUrl})`
+                attribution = attribution ? `${attribution} in ${prLink}` : prLink
+              }
+
+              // Append the attribution string to the subject if we created one
+              // if (attribution && prLink) {
+              //   commit.subject = `${commit.subject} ${attribution} in ${prLink}`;
+              // } else if (prLink) {
+              //   commit.subject = `${commit.subject} ${prLink}`;
+              // } else if (attribution) {
+              //   commit.subject = `${commit.subject} ${attribution}`;
+              // }
+            }
+            return commit
+          },
+          groupBy: 'type',
+          commitGroupsSort: (a, b) => (a.title > b.title ? 1 : -1),
+          commitsSort: ['scope', 'subject'],
+          headerPartial: '',
+          commitPartial: '- {{#if scope}}**{{scope}}:** {{/if}}{{subject}}\n',
+          mainTemplate: `
+{{#if commitGroups}}
+{{#each commitGroups}}
+### {{title}}
+
+{{#each commits}}
+{{> commit root=@root}}
+{{/each}}
+
+{{/each}}
+{{/if}}
+
+{{#if noteGroups}}
+{{#each noteGroups}}
+### {{title}}
+
+{{#each notes}}
+- {{text}}
+{{/each}}
+
+{{/each}}
+{{/if}}
+
+---
+
+Powered by [🍭 CandyPack](https://candypack.dev)
+`
+        }
+      }
+    ],
+    [
+      '@semantic-release/changelog',
+      {
+        changelogFile: 'CHANGELOG.md'
+      }
+    ],
+    '@semantic-release/npm',
+    [
+      '@semantic-release/git',
+      {
+        assets: ['package.json', 'CHANGELOG.md'],
+        message: '🍭 CandyPack v${nextRelease.version} Released'
+      }
+    ],
+    '@semantic-release/github'
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS Guidelines for This Repository
+
+This document provides a comprehensive guide for developers working on the CandyPack source code. It covers the project's architecture, class system, directory structure, and usage patterns.
+
+## 1. Project Overview
+
+CandyPack is a toolkit for building and deploying web applications, consisting of two main parts:
+1.  **A Core System**: A background service that manages servers (web, mail, etc.), process monitoring, and provides a command-line interface (CLI).
+2.  **A Web Framework**: A lightweight framework for building the actual web applications that are served by the core system.
+
+## 2. Core Architecture (`core/Candy.js`)
+
+The heart of the core system is a service container implemented in `core/Candy.js`. This module creates a global singleton object named `Candy`.
+
+### Service Container
+
+The `Candy` object acts as a service locator and dependency injection container. It can dynamically load and cache modules (services) from different parts of the application.
+
+-   **Registration and Resolution**: Modules are registered with a key and can be resolved (retrieved) using that key. The container handles the instantiation of classes and can cache them as singletons.
+-   **Module Loaders**: It has dedicated methods for loading modules from specific directories:
+    -   `Candy.core(name)`: Loads a module from the `core/` directory.
+    -   `Candy.cli(name)`: Loads a module from the `cli/src/` directory.
+    -   `Candy.server(name)`: Loads a module from the `server/src/` directory.
+    -   `Candy.watchdog(name)`: Loads a module from the `watchdog/src` directory.
+
+**Example Usage:**
+To access the application's configuration manager (defined in `core/Config.js`), you would use:
+```javascript
+const config = Candy.core('Config');
+```
+
+## 3. Web Framework Architecture (`framework/src/Candy.js`)
+
+The web framework provides the tools to build a website or API. Its main entry point is `framework/src/Candy.js`. Unlike the core `Candy` object, the framework creates a **request-specific instance** for every incoming HTTP request.
+
+### Request-Specific Context
+
+When a web request hits the server, the framework's `instance()` method is called to create a `_candy` object. This object is a "context" that holds all the necessary components for handling that specific request.
+
+This context object includes:
+-   `Request`: An object representing the incoming HTTP request.
+-   `View`: A view renderer for HTML pages.
+-   `Auth`: An authentication manager.
+-   `Token`: A CSRF token handler.
+-   `Lang`: An internationalization (i18n) helper.
+-   `Mysql`: A database connection handler.
+
+It also attaches numerous helper functions to the context object for convenience within a controller, such as:
+-   `return(data)`: Ends the request and sends data back to the client.
+-   `direct(url)`: Redirects the client to a new URL.
+-   `cookie(key, value)`: Sets a cookie.
+-   `validator()`: Creates a new input validator.
+
+This context object is passed to the controller function that handles the route.
+
+## 4. Directory Structure Guide
+
+-   `bin/`: Executable scripts for the CLI (`candy`, `candypack`).
+-   `cli/`: Source code for the CLI. The main logic is in `cli/src/Cli.js`.
+-   `core/`: Core application logic and shared modules (e.g., `Config.js`, `Commands.js`).
+-   `framework/`: The source code for the web framework.
+-   `server/`: Low-level server implementations (HTTP, Mail, DNS, SSL).
+-   `web/`: **This is a template for a user's website.** When a new site is created with CandyPack, this directory is copied to serve as the starting point.
+    -   `web/index.js`: The entry point for a web application. It initializes the framework.
+    -   `web/route/`: Contains route definition files.
+    -   `web/controller/`: Contains controller files.
+    -   `web/view/`: (Assumed) Would contain HTML templates for the `View` engine.
+    -   `web/config.json`: Application-specific configuration.
+-   `test/`: Project test files.
+-   `watchdog/`: A process monitor that ensures the main CandyPack server stays running.
+
+## 5. Using the CLI (`bin/candy`)
+
+The `candy` command is the main tool for managing the CandyPack server.
+
+-   `candy`: Shows the server status (online/offline, uptime, etc.) and lists available commands.
+-   `candy start`: (Inferred) Starts the CandyPack server daemon.
+-   `candy stop`: (Inferred) Stops the server.
+-   `candy restart`: (Inferred) Restarts the server.
+-   `candy monitor`: Opens an interactive terminal UI to monitor the status of all hosted websites and services.
+-   `candy debug`: Opens an interactive UI to view live logs from different core modules.
+-   `candy help <command>`: Shows detailed help for a specific command.
+
+The commands are defined in `core/Commands.js` and implemented in various modules, primarily `cli/src/Cli.js`.