odac 0.9.0

package/core/Lang.js

@@ -0,0 +1,52 @@
+const fs = require('fs')
+
+class Lang {
+  #locale = Intl.DateTimeFormat().resolvedOptions().locale
+  #file = __dirname + '/../locale/' + this.#locale + '.json'
+  #strings = {}
+  #loaded = false
+
+  constructor() {
+    this.#load()
+  }
+
+  #save() {
+    try {
+      fs.promises.writeFile(this.#file, JSON.stringify(this.#strings, null, 4), 'utf8')
+    } catch (err) {
+      console.error('Error saving language file:', err)
+    }
+  }
+
+  #load() {
+    try {
+      const data = fs.readFileSync(this.#file, 'utf8')
+      this.#loaded = true
+      this.#strings = JSON.parse(data)
+    } catch {
+      this.#strings = {}
+      this.#save()
+    }
+    return true
+  }
+
+  get(key, ...args) {
+    if (!this.#loaded) this.#load()
+    if (key === 'CandyPack') return 'CandyPack'
+    let text = this.#strings[key]
+    if (text === undefined) {
+      text = key
+      this.#strings[key] = text
+      this.#save()
+    }
+    if (args.length > 0) {
+      args.forEach((arg, i) => {
+        if (text.includes(`%s${i + 1}`)) text = text.replace(`%s${i + 1}`, arg)
+        else text = text.replace('%s', arg)
+      })
+    }
+    return text
+  }
+}
+
+module.exports = Lang

package/core/Log.js

@@ -0,0 +1,43 @@
+class Log {
+  #cliMode = false
+
+  constructor() {
+    // Detect if we're running in CLI mode
+    // CLI mode is when the main module is in cli/ or bin/ directory
+    if (require.main && require.main.filename) {
+      const mainFile = require.main.filename
+      this.#cliMode = mainFile.includes('/cli/') || mainFile.includes('/bin/')
+    }
+  }
+
+  init(...arg) {
+    this.module = '[' + arg.join('][') + '] '
+    return {
+      error: this.error.bind(this),
+      log: this.log.bind(this)
+    }
+  }
+
+  error(...arg) {
+    // Always show errors, even in CLI mode
+    console.error(this.module, ...arg)
+  }
+
+  log(...arg) {
+    // Suppress logs in CLI mode to avoid breaking the interface
+    if (this.#cliMode) return
+
+    if (!arg.length) return this
+    if (typeof arg[0] === 'string' && arg[0].includes('%s')) {
+      let message = arg.shift()
+      while (message.includes('%s') && arg.length > 0) {
+        message = message.replace('%s', arg.shift())
+      }
+      message = message.replace(/%s/g, '')
+      arg.unshift(message)
+    }
+    console.log(this.module, ...arg)
+  }
+}
+
+module.exports = Log

package/core/Process.js

@@ -0,0 +1,26 @@
+const findProcess = require('find-process').default
+
+class Process {
+  stop(pid) {
+    return new Promise(resolve => {
+      findProcess('pid', pid)
+        .then(list => {
+          for (const proc of list) if (proc.name == 'node') process.kill(proc.pid, 'SIGTERM')
+        })
+        .catch(() => {})
+        .finally(() => {
+          resolve()
+        })
+    })
+  }
+
+  async stopAll() {
+    if (Candy.core('Config').config.server?.watchdog) await this.stop(Candy.core('Config').config.server.watchdog)
+    if (Candy.core('Config').config.server?.pid) await this.stop(Candy.core('Config').config.server.pid)
+    for (const domain of Object.keys(Candy.core('Config').config?.websites ?? {}))
+      if (Candy.core('Config').config.websites[domain].pid) await this.stop(Candy.core('Config').config.websites[domain].pid)
+    for (const service of Candy.core('Config').config.services ?? []) if (service.pid) await this.stop(service.pid)
+  }
+}
+
+module.exports = Process

package/docs/backend/01-overview/01-whats-in-the-candy-box.md

@@ -0,0 +1,9 @@
+## 🧰 What's in the `Candy` box?
+
+Your `Candy` assistant comes with a bunch of handy services:
+
+*   `Request`: All the details about the user's incoming request.
+*   `View`: A tool to render your beautiful HTML pages.
+*   `Auth`: Your friendly security guard for managing the current user's login.
+*   `Token`: Helps protect the user's forms from nasty CSRF attacks.
+*   `Lang`: A helper for translating your app into the user's language.

package/docs/backend/01-overview/02-super-handy-helper-functions.md

@@ -0,0 +1,9 @@
+## ✨ Super-Handy Helper Functions
+
+On top of that, `Candy` has some quick-and-easy helper functions:
+
+*   `return(data)`: Quickly send a response back to the user and you're done.
+*   `direct(url)`: Need to send the user to another page? This is your tool.
+*   `cookie(key, value)`: Leave a little cookie in the user's browser.
+*   `env(key, defaultValue)`: Access environment variables with an optional default value.
+*   `validator()`: A powerful tool to check the user's submitted data.

package/docs/backend/01-overview/03-development-server.md

@@ -0,0 +1,79 @@
+## 🚀 Development Server
+
+CandyPack provides a built-in development server that allows you to test your website locally without running the full CandyPack server infrastructure.
+
+### Quick Start
+
+Navigate to your website directory and run one of these commands:
+
+```bash
+# Using npm script
+npm start
+
+# Using CandyPack directly
+candypack framework run
+```
+
+Both commands will start a local development server on port `1071` by default, and your website will be accessible at `http://127.0.0.1:1071`.
+
+### Custom Port
+
+You can specify a custom port by adding it as an argument:
+
+```bash
+# Using npm script with custom port
+npm start 8080
+
+# Using CandyPack directly with custom port
+candypack framework run 8080
+```
+
+This will start the server on your specified port (e.g., `http://127.0.0.1:8080`).
+
+### Development vs Production
+
+The development server (`npm start`) is designed for:
+
+- **Local testing** and development only
+- **Quick iteration** without server setup
+- **Debugging** your application logic
+- **Testing on localhost** (127.0.0.1)
+
+**Important**: The development server does NOT provide DNS, SSL, or other production services.
+
+For production deployment with full CandyPack server features, create your website using:
+
+```bash
+candy web create
+```
+
+This registers your website with the CandyPack server and provides:
+
+- **Automatic SSL** certificate management
+- **DNS handling** for your domain
+- **Multi-domain hosting** capabilities
+- **Process monitoring** and auto-restart
+- **Production optimizations** and security
+
+### Package.json Scripts
+
+When you create a new website, CandyPack automatically generates a `package.json` with these useful scripts:
+
+```json
+{
+  "scripts": {
+    "start": "candy framework run",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}
+```
+
+- `npm start` - Starts the development server for local testing
+- `npm test` - Placeholder for your test suite
+
+### Tips
+
+- The development server automatically detects changes in your code
+- Use `Ctrl+C` to stop the development server
+- The server will show helpful error messages in the console
+- All CandyPack framework features are available in development mode

package/docs/backend/02-structure/01-typical-project-layout.md

@@ -0,0 +1,39 @@
+## 📂 Typical Project Layout
+
+Let's take a look at a typical project layout:
+
+-   `project_root/`
+    -   `config.json`: This is where you'll keep your app's secrets and settings, like database passwords or API keys.
+    -   `index.js`: The starting pistol for your web application! This file kicks off the CandyPack framework.
+    -   `package.json`: Contains project metadata and npm scripts for development. Automatically generated when creating a new website.
+    -   `public/`: All files placed in this folder are directly accessible from the outside. This is the perfect place for your images, stylesheets, and client-side JavaScript.
+    -   `route/`: This folder holds all your route definitions. The filename of the route file corresponds to the subdomain it serves.
+        -   `www.js`: Used for routes on your main domain (e.g., `www.example.com` or `example.com`).
+        -   `api.js`: Used for routes on a subdomain (e.g., `api.example.com`). When a request comes in for `api.example.com`, this is the route file that gets used. You can create files for any subdomain!
+    -   `controller/`: This is where the magic happens! Controllers contain the main logic for your application.
+        -   `page/`: We suggest putting controllers that show HTML pages in here.
+        -   `api/`: If you're building an API, it's a great idea to keep those controllers separate in their own folder.
+    -   `view/`: For all your HTML template files. This is what your users will see.
+
+### Development Commands
+
+Your `package.json` includes helpful npm scripts for development:
+
+```bash
+# Start development server (default port 1071)
+npm start
+
+# Start development server on custom port
+npm start 8080
+```
+
+You can also use CandyPack commands directly:
+
+```bash
+# Development server (local testing only)
+candypack framework run [port]
+```
+
+**Note**: For production websites with DNS and SSL, use `candy web create` to register with CandyPack server.
+
+Following this structure helps keep your code's responsibilities separate. Your routing logic lives in one place, your app logic in another, and your presentation files in a third. It's a recipe for success!

package/docs/backend/03-config/00-configuration-overview.md

@@ -0,0 +1,214 @@
+## ⚙️ Configuration Overview
+
+CandyPack uses a simple and flexible configuration system based on `config.json` and optional `.env` files. You can choose the approach that best fits your needs.
+
+### Configuration Files
+
+#### config.json (Required)
+The main configuration file located in your website's root directory. This file contains all your application settings in JSON format.
+
+```json
+{
+  "request": {
+    "timeout": 30000
+  },
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "secret123",
+    "database": "myapp"
+  }
+}
+```
+
+#### .env (Optional)
+An optional environment variables file for storing sensitive information like passwords and API keys. This file should be added to `.gitignore` to keep secrets out of version control.
+
+```bash
+# .env
+MYSQL_PASSWORD=super_secret_123
+API_KEY=your_api_key_here
+NODE_ENV=production
+```
+
+### Three Ways to Configure
+
+#### 1. Direct Values (Simple)
+Perfect for development or non-sensitive settings:
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "password": "dev123"
+  }
+}
+```
+
+#### 2. Environment Variables (Secure)
+Use `${VARIABLE}` syntax in `config.json` to reference `.env` values:
+
+```json
+{
+  "mysql": {
+    "host": "${MYSQL_HOST}",
+    "password": "${MYSQL_PASSWORD}"
+  }
+}
+```
+
+```bash
+# .env
+MYSQL_HOST=production.db.com
+MYSQL_PASSWORD=super_secret_123
+```
+
+#### 3. Mixed Approach (Flexible)
+Combine both methods - use direct values for non-sensitive data and environment variables for secrets:
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "myapp"
+  },
+  "api": {
+    "endpoint": "https://api.example.com",
+    "key": "${API_KEY}"
+  }
+}
+```
+
+### Accessing Configuration
+
+#### In Controllers
+You can access configuration values in three ways:
+
+```javascript
+// 1. From Candy.Config (recommended for structured config)
+const dbHost = Candy.Config.mysql.host
+
+// 2. Using Candy.env() helper
+const apiKey = Candy.env('API_KEY')
+const debug = Candy.env('DEBUG', 'false')
+
+// 3. Direct process.env access
+const nodeEnv = process.env.NODE_ENV
+```
+
+### Best Practices
+
+**Development:**
+- Use direct values in `config.json` for quick setup
+- Keep development credentials simple
+
+**Production:**
+- Store sensitive data in `.env` file
+- Add `.env` to `.gitignore`
+- Use environment variables for passwords, API keys, and tokens
+- Copy `.env.example` to `.env` and fill in production values
+
+**Version Control:**
+- Commit `config.json` with `${VARIABLE}` placeholders
+- Commit `.env.example` with dummy values
+- Never commit `.env` with real credentials
+
+### Common Configuration Options
+
+**Request timeout:**
+```json
+{
+  "request": {
+    "timeout": 30000
+  }
+}
+```
+
+**Database connection:**
+```json
+{
+  "database": {
+    "host": "localhost",
+    "user": "root",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "myapp"
+  }
+}
+```
+
+**Authentication sessions:**
+```json
+{
+  "auth": {
+    "table": "users",
+    "token": "user_tokens",
+    "maxAge": 2592000000,
+    "updateAge": 86400000
+  }
+}
+```
+
+**Early Hints (HTTP 103):**
+```json
+{
+  "earlyHints": {
+    "enabled": true,
+    "auto": true,
+    "maxResources": 5
+  }
+}
+```
+
+Early Hints is a performance optimization feature that works automatically without any configuration. The server sends preliminary HTTP headers to the browser before the final response, allowing browsers to start preloading critical resources (CSS, JavaScript, fonts) earlier. This is completely zero-config - it detects resources from your HTML automatically and sends hints on subsequent requests.
+
+See individual documentation sections for detailed configuration options.
+
+### Example Setup
+
+**config.json** (committed to git):
+```json
+{
+  "request": {
+    "timeout": 30000
+  },
+  "mysql": {
+    "host": "${MYSQL_HOST}",
+    "user": "${MYSQL_USER}",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "myapp"
+  },
+  "auth": {
+    "maxAge": 2592000000,
+    "updateAge": 86400000
+  },
+  "mail": {
+    "from": "${MAIL_FROM}"
+  }
+}
+```
+
+**.env.example** (committed to git):
+```bash
+# Database
+MYSQL_HOST=localhost
+MYSQL_USER=root
+MYSQL_PASSWORD=your_password_here
+
+# Mail
+MAIL_FROM=noreply@example.com
+```
+
+**.env** (gitignored, not committed):
+```bash
+# Database
+MYSQL_HOST=production.db.com
+MYSQL_USER=prod_user
+MYSQL_PASSWORD=super_secret_production_password
+
+# Mail
+MAIL_FROM=noreply@myapp.com
+```
+
+This approach keeps your code secure while maintaining flexibility across different environments.

package/docs/backend/03-config/01-database-connection.md

@@ -0,0 +1,60 @@
+## 🔌 Database Connection
+
+When you add a `mysql` object to your `config.json`, the system will automatically connect to your MySQL database. No separate connection setup is needed in your code.
+
+### Basic Configuration
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "your_user",
+    "password": "your_password",
+    "database": "your_database"
+  }
+}
+```
+
+Once this is configured, you can directly use `Candy.Mysql` commands to run queries.
+
+### Using Environment Variables
+
+For better security, especially in production, you can use environment variables for sensitive information:
+
+**config.json:**
+```json
+{
+  "mysql": {
+    "host": "${MYSQL_HOST}",
+    "user": "${MYSQL_USER}",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "myapp"
+  }
+}
+```
+
+**.env:**
+```bash
+MYSQL_HOST=localhost
+MYSQL_USER=root
+MYSQL_PASSWORD=super_secret_123
+```
+
+The `.env` file should be added to `.gitignore` to keep your credentials secure.
+
+### Mixed Approach
+
+You can also mix direct values with environment variables:
+
+```json
+{
+  "mysql": {
+    "host": "localhost",
+    "user": "root",
+    "password": "${MYSQL_PASSWORD}",
+    "database": "myapp"
+  }
+}
+```
+
+This way, non-sensitive values are directly in the config while passwords remain in the `.env` file.

package/docs/backend/03-config/02-static-route-mapping-optional.md

@@ -0,0 +1,20 @@
+## 🗺️ Static Route Mapping (Optional)
+
+Normally, all publicly served files should be in your `public` folder. However, if you need to expose a specific file from somewhere else on your server, you can use the optional `route` object in your `config.json`. This creates a direct mapping from a URL path to that file.
+
+```json
+"route": {
+  "/assets/js/candy.js": "${candy}/framework/web/candy.js",
+  "/css/main.css": "/path/to/your/project/assets/css/main.css"
+}
+```
+
+When a user visits a URL that matches a key in the `route` object, CandyPack will serve the corresponding file from your filesystem.
+
+#### Using the `${candy}` Variable
+
+The special variable `${candy}` is a shortcut that points to the root directory where CandyPack is installed. This is helpful for linking to files that are part of the framework itself.
+
+#### Absolute Paths
+
+For your own project files, you should provide a full, absolute path to the file on your server.

package/docs/backend/03-config/03-request-timeout.md

@@ -0,0 +1,11 @@
+## ⏱️ Request Timeout
+
+You can configure the global timeout for incoming requests by adding a `request` object to your `config.json`.
+
+```json
+"request": {
+  "timeout": 10000
+}
+```
+
+The `timeout` value is in milliseconds. In this example, any request that takes longer than 10,000 milliseconds (10 seconds) to process will be timed out.