nibula 1.0.2 → 1.1.1

package/docs/Deploy.md

@@ -1,79 +1,85 @@
 # Server Configuration
 
-Nibula builds a static site into your output folder (`out`). To put it
-online you upload that folder to a web server. Which server config you need
-depends on **where** you publish.
+Nibula builds a static site into your output folder (`out`). To put it online you
+upload that folder to a web server. Which server config you need depends on
+**where** you publish and **which backend** you chose at scaffold time (PHP or
+Node.js — see `docs/Backend.md`).
 
-## Where to publish
+The shipped `.htaccess`, `web.config` and `nginx.conf` are written to cover
+**both** backends, so you don't swap config files based on your choice. There is
+one caveat on Apache/IIS, explained at the end.
 
-### Shared hosting (Apache — e.g. Aruba, most cPanel providers)
+## Prerequisites
+
+**PHP backend:** a server with PHP support (Apache, Nginx + PHP-FPM, or IIS +
+FastCGI) and Composer for the backend dependencies. Works on typical shared
+hosting.
 
-The most common and beginner-friendly option. You rent space on a server that's
-already set up, and you just upload your files.
+**Node backend:** Node.js 18+ on the server and the ability to run a
+long-running process — i.e. a VPS you control, not typical shared hosting. No PHP
+or Composer required.
+
+## Where to publish
 
-In short: take the **contents of the `out` folder** and upload them to the
-hosting's public web root (often called `htdocs`, `public_html`, or `www`).
-That's it — the site is live.
+### Shared hosting (Apache — e.g. Aruba, most cPanel providers)
 
-On this kind of hosting the server usually runs **Apache** (or **IIS** on Windows
-hosts). This is where `.htaccess` (Apache) or `web.config` (IIS) come in: they're
-already inside your `out` folder and get picked up automatically, with no extra
-setup. They handle security and routing for you (see below).
+The most common and beginner-friendly option, and the natural home for the
+**PHP** backend (shared hosting can't keep a Node process alive). You rent space
+on a server that's already set up and just upload your files.
 
-> You don't need to understand the details to publish — upload `out`, and the
-> config files do their job. The sections below explain what they protect.
+Take the **contents of the `out` folder** and upload them to the hosting's public
+web root (often `htdocs`, `public_html`, or `www`). That's it — the site is live.
+`.htaccess` (Apache) or `web.config` (IIS) are already inside `out` and get picked
+up automatically, handling security and routing for you.
 
 ### Your own server (Nginx — e.g. an Ubuntu VPS)
 
 If you rent a bare server (a VPS) and install everything yourself, it typically
 runs **Nginx** on **Ubuntu Server**. Here nothing is pre-configured: you set up
-Nginx, PHP, and the security rules by hand. This is more powerful but requires
-knowing what you're doing — if this is your path, read up on Nginx server
-administration first. The Nginx section below gives you the essential rules to
-start from.
+Nginx, the backend, and the security rules by hand. This is the setup for the
+**Node** backend (and also works for PHP + PHP-FPM). The Nginx section below
+gives you the essential rules to start from.
 
 ---
 
 ## Apache (`.htaccess`)
 
-`.htaccess` files at `src/frontend/` and `src/backend/` are automatically copied
-into the build output by Eleventy. No setup required — upload `out` and Apache
-reads them on its own.
+`.htaccess` files at `src/frontend/` and `src/backend/` are copied into the build
+output by Eleventy. No setup required — upload `out` and Apache reads them.
 
 They cover:
 - Directory listing disabled
 - 403 / 404 → `/404.html`
 - Sensitive files blocked (`web.config`, dotfiles, etc.)
 - Backend source directory sealed — all access funnels through the front controller
-- `/api/*` → `backend/_core/index.php`
-- HTTPS redirect
+- `/api/*` routing (see the dual-backend note below)
 
-This is the config that makes shared hosting like Aruba work out of the box.
+**Dual backend:** if `mod_proxy` is available, `/api` is reverse-proxied to the
+Node backend (`127.0.0.1:3000`); if not (typical shared hosting), `/api` is
+rewritten to the PHP front controller. To force PHP on a server that *has*
+`mod_proxy`, comment the `mod_proxy` block in `.htaccess`.
 
 ## IIS (`web.config`)
 
 For Windows-based hosting. `web.config` files at `src/frontend/` and
-`src/backend/` are automatically copied into the build output by Eleventy, and
-IIS reads them automatically — same idea as `.htaccess`, different server.
+`src/backend/` are copied into the build output by Eleventy and read
+automatically — same idea as `.htaccess`, different server.
 
-Covers the same rules as the Apache configuration above.
+**Dual backend:** the `ApiToNode` rewrite rule (requires the ARR + URL Rewrite
+modules) reverse-proxies `/api` to Node and wins if present. To use PHP instead,
+remove the `ApiToNode` rule; the `ApiToPhp` fallback then rewrites `/api` to the
+PHP front controller.
 
 ## Nginx
 
-Used when you run your **own Ubuntu Server** (a VPS). Unlike Apache and IIS,
-Nginx does **not** read per-directory config files, so there's nothing automatic
-here.
+Used when you run your **own Ubuntu Server** (a VPS). Unlike Apache and IIS, Nginx
+does **not** read per-directory config files, so there's nothing automatic here.
 
 **`nginx.conf` in the project root is not a ready-to-use file.** It is a set of
-directives that you must take and adapt into a complete Nginx `server { }`
-block — the one that defines your domain (`server_name`), ports (`listen`), and
-SSL certificates. Paste these rules inside your own server block and adjust
-`root` to point to your `out` folder.
-
-These directives are the **minimum Nginx equivalent of `.htaccess` and
-`web.config`**: their job is to not expose dangerous files (server config files,
-the backend source directory) and to route the API correctly. Without them, an
-Nginx server would serve your site but leave those files reachable.
+directives you adapt into a complete Nginx `server { }` block — the one that
+defines your domain (`server_name`), ports (`listen`), and SSL certificates.
+Paste these rules inside your own server block and set `root` to your `out`
+folder.
 
 They provide:
 - `server_tokens off` — hides the Nginx version
@@ -81,21 +87,104 @@ They provide:
 - 403 / 404 → `/404.html`
 - Backend source directory (`/backend/`) sealed with `return 404`
 - Server config files (`.htaccess`, `web.config`) blocked anywhere in the tree
-- `/api/*` routed to the PHP front controller
+- `/api/*` routed to the backend (see below)
 - Security headers on static responses
 
-> Setting up Nginx correctly (SSL, HTTPS redirect, PHP-FPM) goes beyond these
-> rules. If you plan to publish with Nginx, read up on Nginx + PHP-FPM on Ubuntu
-> Server first — these directives are the security starting point, not a full
-> server setup.
+**Dual backend (auto-fallback):** the shipped `nginx.conf` sends `/api` to the
+Node backend on `127.0.0.1:3000` and, if Node is unreachable (502/504), falls
+back automatically to the PHP front controller. So the same config works whether
+you deployed Node or PHP — Nginx is the only server that can do this fallback
+automatically.
+
+> Setting up Nginx fully (SSL, HTTPS redirect, PHP-FPM and/or the Node service)
+> goes beyond these rules. These directives are the security starting point, not
+> a complete server setup.
 
 ### PHP-FPM socket
 
-The socket path in the `/api/` rule targets RHEL / Fedora by default. On Ubuntu
-the socket name includes the PHP version — check with `ls /run/php/` and adjust:
+When using the PHP path, the socket in the `/api` fallback targets Debian/Ubuntu
+by default. Check with `ls /run/php/` and adjust:
 
 | Distro | Path |
 |---|---|
-| RHEL / Fedora | `unix:/run/php-fpm/php-fpm.sock` |
 | Debian / Ubuntu | `unix:/run/php/php8.3-fpm.sock` |
-| TCP fallback | `127.0.0.1:9000` |
+| RHEL / Fedora | `unix:/run/php-fpm/php-fpm.sock` |
+| TCP fallback | `127.0.0.1:9000` |
+
+---
+
+## Starting the Node backend on the server
+
+Unlike PHP, the Node backend is **not** executed by the web server per request —
+it is a process you start and keep alive. After uploading your built `out` folder:
+
+1. Install the backend's runtime deps (only needed if an endpoint uses the DB):
+   ```bash
+   cd /var/www/your-site/out/backend
+   npm install
+   ```
+
+2. Make sure `config.js` exists in `out/backend/` (copy `example.config.js` to
+   `config.js` if missing) and fill in your values.
+
+3. Start it — quick test first:
+   ```bash
+   node _core/index.js
+   # -> [backend-node] listening on http://127.0.0.1:3000 (env: production)
+   ```
+   Then, from the server, confirm it answers:
+   ```bash
+   curl http://127.0.0.1:3000/api/example-public
+   ```
+
+   > Running `node _core/index.js` directly ties the process to your SSH session —
+   > close the terminal and the backend dies. The recommended way to try it out
+   > without staying stuck there is **`screen`** (a detachable terminal):
+   > ```bash
+   > screen -S backend            # open a named session
+   > node _core/index.js          # start the backend inside it
+   > # press Ctrl+A then D to detach — the backend keeps running
+   > # reattach later with:  screen -r backend
+   > ```
+   > `screen` is perfect for testing and small setups. For a real production
+   > deployment that also restarts on crash/reboot, prefer **systemd** (step 4).
+
+4. To keep it running after logout, use **systemd**. An example unit ships at
+   `backend/backend-node.service.example` — copy it to
+   `/etc/systemd/system/backend-node.service`, adjust `WorkingDirectory` and the
+   `node` path (`which node`), then:
+   ```bash
+   sudo systemctl daemon-reload
+   sudo systemctl enable --now backend-node
+   sudo systemctl status backend-node
+   ```
+   (`pm2` also works: `pm2 start _core/index.js --name backend-node`.)
+
+The web server then reverse-proxies `/api` to this process; with the shipped
+`nginx.conf`, if Node is down Nginx falls back to PHP automatically.
+
+### Environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `3000` | Port Node listens on (match your proxy target) |
+| `HOST` | `127.0.0.1` | Bind address (keep it local; the web server is the public face) |
+| `APP_ENV` | `production` | `production` hides error details; anything else = verbose 500s |
+| `DOCUMENT_ROOT` | auto (`out/`) | Where `404.html` lives; auto-detected as the folder above `backend/` |
+
+---
+
+## The one caveat on Apache and IIS
+
+Nginx can health-check the Node upstream and fall back to PHP automatically.
+Apache (`.htaccess`) and IIS (`web.config`) **cannot** — a per-directory config
+can't know whether Node is up. So there the routing is decided by configuration,
+not at runtime:
+
+- **Apache:** `mod_proxy` present → Node; absent → PHP. Comment the `mod_proxy`
+  block to force PHP on a proxy-enabled server.
+- **IIS:** `ApiToNode` rule present (needs ARR) → Node; remove it to use the
+  `ApiToPhp` fallback.
+
+Since a given deployment runs only one backend, this is a one-time setup, not a
+per-request concern.

package/nginx.conf

@@ -1,10 +1,22 @@
+# Example nginx directives for a Nibula site — covers BOTH backends.
+#
+# /api is served by Node (index.js) if it is running on 127.0.0.1:3000; if Node
+# is unreachable, nginx falls back to the PHP front controller automatically.
+# So the same config works whether you deployed the Node backend or the PHP one:
+#   - Node backend running  -> Node answers /api
+#   - only PHP deployed      -> Node is down -> falls back to PHP-FPM
+#
+# This is NOT a ready-to-use file: paste these directives inside your own
+# server { } block (the one with server_name, listen and SSL) and set `root`
+# to your `out` folder.
+
 # Hide the nginx version from response headers
 server_tokens off;
 
 # Force HTTPS on future requests (applies site-wide, including /api)
 add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
 
-root /var/www/html/out;
+root /var/www/your-site/out;
 index index.html;
 
 # Disable directory listing
@@ -15,24 +27,40 @@ location = /404.html {
     internal;
 }
 
-# Never expose the backend source directory
+# Never expose the backend source directory over HTTP.
 location ^~ /backend/ {
     return 404;
 }
 
 # Block server config files anywhere in the tree (.htaccess, web.config).
-# return 404 is served internally as /404.html via error_page above.
 location ~* (^|/)(\.htaccess|web\.config)$ {
     return 404;
 }
 
-# Route all /api/ requests to the PHP front controller.
-# Security headers for API responses are set by the front controller (PHP).
+# --- /api: Node primary, PHP fallback ---------------------------------------
+# Try the Node backend first. If it is down (502/504), retry through the PHP
+# front controller. Security headers for API responses are set by the backend.
 location ^~ /api/ {
-    try_files $uri =404;
-    fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
-    fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    proxy_intercept_errors on;
+    error_page 502 504 = @php_backend;
+}
+
+location @php_backend {
     include fastcgi_params;
+    fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
+
+    # Adjust the PHP-FPM socket to your distro:
+    #   Debian / Ubuntu : unix:/run/php/php8.3-fpm.sock
+    #   RHEL / Fedora   : unix:/run/php-fpm/php-fpm.sock
+    #   TCP fallback    : 127.0.0.1:9000
+    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
 }
 
 # Serve static files, fall back to the 404 page.
@@ -44,4 +72,4 @@ location / {
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
     add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
     try_files $uri $uri/ /404.html;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "A beginner-friendly static site generator built on Eleventy that stays close to vanilla HTML, CSS and JS — with a page-management CLI, an optional PHP backend, and SEO files generated for you.",
   "keywords": [
     "static-site-generator",

package/src/backend/_core/index.js

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/index.php  (the front controller).
+ *
+ * PHP was invoked once per request by the web server through PHP-FPM. Node is
+ * the server itself, so this file boots an HTTP listener and runs the exact same
+ * pipeline for every request:
+ *
+ *   1. request parsing (strip /api prefix, split segments, reject . / ..)
+ *   2. endpoint resolution (dynamic routing with subdirectories + route params)
+ *   3. headers + CORS
+ *   4. rate limiting
+ *   5. authentication guard for protected endpoints
+ *   6. dispatch to the matched endpoint file
+ *
+ * Endpoints keep the same authoring style as PHP: a file that receives
+ * { method, requestParams, Response, ... } and calls Response.success/error.
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { createResponse, HALT } = require('./modules/Response');
+const RateLimiter = require('./modules/RateLimiter');
+const { loadConfig, handleException } = require('./init');
+
+const CORE_PATH = __dirname;
+
+// Load configuration once (init.php loaded it per invocation; here per process).
+const config = loadConfig();
+
+// Environment: mirror the display_errors toggle by picking the debug flag.
+const APP_ENV = config.APP_ENV || 'production';
+
+// Where to look for the 404.html generated by the static build.
+// In a Nibula build the backend lives at out/backend/, so the site root (out/)
+// is two levels up from _core. We default to that, so 404.html is found without
+// any extra configuration; override with the DOCUMENT_ROOT env var if needed.
+// (equivalent of $_SERVER['DOCUMENT_ROOT'] in the PHP front controller).
+const DOCUMENT_ROOT = process.env.DOCUMENT_ROOT || path.join(CORE_PATH, '..', '..');
+
+const basePublic = path.join(CORE_PATH, '..', 'api', 'public');
+const baseProtected = path.join(CORE_PATH, '..', 'api', 'protected');
+
+/**
+ * hash_equals equivalent: constant-time string comparison, safe on unequal
+ * lengths (timingSafeEqual throws if buffers differ in length).
+ */
+function hashEquals(known, given) {
+    const a = Buffer.from(String(known));
+    const b = Buffer.from(String(given));
+    if (a.length !== b.length) {
+        return false;
+    }
+    return crypto.timingSafeEqual(a, b);
+}
+
+/** Serve the static 404 page if available, else a plain fallback. */
+function send404(res) {
+    res.statusCode = 404;
+    const errorPage = DOCUMENT_ROOT ? path.join(DOCUMENT_ROOT, '404.html') : '';
+    if (errorPage && fs.existsSync(errorPage)) {
+        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
+        res.end(fs.readFileSync(errorPage));
+    } else {
+        res.setHeader('Content-Type', 'text/html; charset=UTF-8');
+        res.end('<h1>404 Not Found</h1>The requested URL was not found on this server.');
+    }
+}
+
+/** Read and JSON-parse the request body (available to endpoints as ctx.body). */
+function readBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (!raw) return resolve({ raw: '', json: null });
+            let json = null;
+            try { json = JSON.parse(raw); } catch (e) { json = null; }
+            resolve({ raw, json });
+        });
+        req.on('error', () => resolve({ raw: '', json: null }));
+    });
+}
+
+async function handleRequest(req, res) {
+    const Response = createResponse(res);
+
+    try {
+        // =====================================================
+        // 1. REQUEST PARSING
+        // =====================================================
+        const method = req.method;
+        const parsedUrl = new URL(req.url, 'http://localhost');
+        let uri = parsedUrl.pathname;
+
+        // Strip a leading /api, then trim trailing slash (rtrim(..., '/') ?: '/').
+        uri = uri.replace(/^\/api/, '');
+        uri = uri.replace(/\/+$/, '');
+        if (uri === '') uri = '/';
+
+        const parts = uri.split('/').filter((p) => p !== '');
+
+        for (const part of parts) {
+            if (part === '..' || part === '.') {
+                Response.error('Bad Request', 400);
+            }
+        }
+
+        // =====================================================
+        // 2. ENDPOINT RESOLUTION (ROUTING WITH SUBDIRECTORIES)
+        // =====================================================
+        let endpointFile = null;
+        let isProtected = false;
+
+        const checkParts = parts.slice();
+        const params = [];
+
+        while (checkParts.length > 0) {
+            const relativePath = checkParts.join('/') + '.js';
+
+            const publicCandidate = path.join(basePublic, relativePath);
+            if (fs.existsSync(publicCandidate)) {
+                endpointFile = publicCandidate;
+                isProtected = false;
+                break;
+            }
+
+            const protectedCandidate = path.join(baseProtected, relativePath);
+            if (fs.existsSync(protectedCandidate)) {
+                endpointFile = protectedCandidate;
+                isProtected = true;
+                break;
+            }
+
+            // No match: peel the last segment as a route param and retry.
+            params.unshift(checkParts.pop());
+        }
+
+        // No endpoint → HTML 404 page.
+        if (!endpointFile) {
+            send404(res);
+            return;
+        }
+
+        // Compute the endpoint path (relative, without extension) used as the key
+        // for CUSTOM_ENDPOINT_KEYS / CUSTOM_ENDPOINT_ORIGINS.
+        const base = isProtected ? baseProtected : basePublic;
+        let endpointPath = endpointFile
+            .split(path.sep).join('/')
+            .replace(base.split(path.sep).join('/'), '')
+            .replace(/\.js$/, '')
+            .replace(/^\//, '');
+
+        // =====================================================
+        // 3. HEADERS AND CORS (only if the endpoint exists)
+        // =====================================================
+        res.setHeader('Content-Type', 'application/json; charset=UTF-8');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('X-Frame-Options', 'DENY');
+        res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Api-Key');
+
+        const originsForEndpoint =
+            (config.CUSTOM_ENDPOINT_ORIGINS && config.CUSTOM_ENDPOINT_ORIGINS[endpointPath]) ||
+            config.GENERAL_ALLOWED_ORIGINS ||
+            [];
+
+        const origin = req.headers['origin'] || '';
+
+        if (origin !== '' && originsForEndpoint.includes(origin)) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Vary', 'Origin');
+        } else if (originsForEndpoint.includes('*')) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        }
+
+        if (method === 'OPTIONS') {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+
+        // Rate limit: 60 requests / 60 seconds per IP (same defaults as PHP).
+        const ip = (req.headers['x-forwarded-for'] || '').split(',')[0].trim()
+            || req.socket.remoteAddress
+            || '';
+        RateLimiter.check(ip, 60, 60, Response, res);
+
+        // =====================================================
+        // 4. AUTHENTICATION GUARD
+        // =====================================================
+        if (isProtected) {
+            const validKey =
+                (config.CUSTOM_ENDPOINT_KEYS && config.CUSTOM_ENDPOINT_KEYS[endpointPath]) ||
+                config.GENERAL_API_KEY ||
+                '';
+            const apiKey = req.headers['x-api-key'] || '';
+
+            if (validKey === '' || !hashEquals(validKey, apiKey)) {
+                Response.error('Unauthorized. X_API_KEY is incorrect or missing', 401);
+            }
+        }
+
+        // =====================================================
+        // 5. DISPATCH
+        // =====================================================
+        const body = await readBody(req);
+
+        // eslint-disable-next-line import/no-dynamic-require, global-require
+        const handler = require(endpointFile);
+
+        const context = {
+            method,               // HTTP method
+            requestParams: params, // leftover URL segments (route params)
+            Response,             // request-bound Response helper
+            query: Object.fromEntries(parsedUrl.searchParams), // parsed query string
+            body: body.json,      // parsed JSON body (or null)
+            rawBody: body.raw,    // raw body string
+            headers: req.headers,
+            req,
+            res,
+            config,
+            CORE_PATH,
+        };
+
+        await handler(context);
+
+        // If the endpoint returned without sending a response, mirror PHP's
+        // implicit end of script: nothing more to do. Close if still open.
+        if (!res.writableEnded) {
+            res.end();
+        }
+    } catch (err) {
+        if (err === HALT) {
+            // A response was already sent; unwind quietly (≈ PHP exit).
+            return;
+        }
+        // set_exception_handler equivalent: any real error → 500.
+        try {
+            handleException(err, config, Response);
+        } catch (inner) {
+            if (inner === HALT) return;
+            if (!res.writableEnded) {
+                res.statusCode = 500;
+                res.end(JSON.stringify({ status: 'error', message: 'Internal server error', code: 500 }));
+            }
+        }
+    }
+}
+
+const HOST = process.env.HOST || '127.0.0.1';
+const PORT = parseInt(process.env.PORT || '3000', 10);
+
+const server = http.createServer(handleRequest);
+
+server.listen(PORT, HOST, () => {
+    // eslint-disable-next-line no-console
+    console.log(`[backend-node] listening on http://${HOST}:${PORT} (env: ${APP_ENV})`);
+});
+
+module.exports = server;

package/src/backend/_core/init.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Mirror of src/backend/_core/init.php
+ *
+ * init.php did three things:
+ *   1. registered a global exception handler that turns any throwable into a
+ *      500 JSON response (verbose in debug, generic in production);
+ *   2. registered an error handler that promoted PHP warnings to exceptions;
+ *   3. loaded config.php.
+ *
+ * In Node there is no per-request global handler, so the exception-to-500
+ * translation lives in the front controller (index.js), which calls
+ * handleException() below. Here we expose config loading and that helper.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load configuration. dirname(__dirname) in PHP pointed at the folder holding
+ * config.php (the backend root). Here that is the parent of _core.
+ * If config.js is missing (e.g. fresh clone) we fall back to example.config.js,
+ * mirroring the "copy example.config to config" guidance.
+ */
+function loadConfig() {
+    const backendRoot = path.join(__dirname, '..');
+    const configPath = path.join(backendRoot, 'config.js');
+    const examplePath = path.join(backendRoot, 'example.config.js');
+
+    if (fs.existsSync(configPath)) {
+        return require(configPath);
+    }
+    return require(examplePath);
+}
+
+/**
+ * Turn any thrown error into a 500 response, mirroring set_exception_handler.
+ * @param {Error} exception
+ * @param {object} config
+ * @param {object} Response request-bound helper
+ */
+function handleException(exception, config, Response) {
+    const isDebug = (config.APP_ENV || 'production') !== 'production';
+    Response.error(
+        isDebug ? exception.message : 'Internal server error',
+        500,
+        isDebug ? { stack: exception.stack } : null
+    );
+}
+
+module.exports = { loadConfig, handleException };