nibula 2.4.7 → 3.0.0

package/src/backend/endpoints/protected/example-protected.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+require_once CORE_PATH . '/modules/Validate.php';
+
+/**
+ * Return one closure per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself.
+ *
+ * Each closure receives $request, an array with:
+ *   method         the HTTP method, as a string
+ *   requestParams  extra URL segments after the endpoint path
+ *   query          query string values: ?page=2 gives ['page' => '2']
+ *   body           the JSON body, already decoded into an array
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.php
+ *
+ * Response::success($data, $code) and Response::error($message, $code) send the
+ * answer and stop the request: nothing after them runs.
+ */
+
+return [
+    'get' => function (array $request) {
+        Response::success([
+            'message' => 'Endpoint is working',
+            'params'  => $request['requestParams'],
+            'query'   => $request['query'],
+        ]);
+    },
+
+    'post' => function (array $request) {
+        $body = $request['body'];
+
+        // Validate:: stops the request with a 422 when a value is missing or
+        // malformed, so the returned value is always safe to use.
+        $name  = Validate::required($body['name'] ?? null, 'name');
+        $email = Validate::email($body['email'] ?? null, 'email');
+
+        Response::success([
+            'name'  => $name,
+            'email' => $email,
+        ], 201);
+    },
+];

package/src/backend/endpoints/public/example-public.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/**
+ * Export one function per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself.
+ *
+ * Each function receives the request context:
+ *   method         the HTTP method, as a string
+ *   requestParams  extra URL segments after the endpoint path
+ *   query          query string values: ?page=2 gives { page: '2' }
+ *   body           the JSON body, already parsed into an object
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.js
+ *   Response       sends the answer
+ *   Validate       checks incoming values
+ *
+ * Response.success(data, code) and Response.error(message, code) send the
+ * answer and stop the request: nothing after them runs.
+ */
+
+module.exports = {
+  get: ({ requestParams, query, Response }) => {
+    Response.success({
+      message: "Endpoint is working",
+      params: requestParams,
+      query: query,
+    });
+  },
+
+  post: ({ body, Response, Validate }) => {
+    // Validate stops the request with a 422 when a value is missing or
+    // malformed, so the returned value is always safe to use.
+    const name = Validate.required(body.name, "name");
+    const email = Validate.email(body.email, "email");
+
+    Response.success({ name, email }, 201);
+  },
+};

package/src/backend/endpoints/public/example-public.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+require_once CORE_PATH . '/modules/Validate.php';
+
+/**
+ * Return one closure per HTTP method you want to support. Any other method
+ * gets an automatic 405, so you never have to check the method yourself
+ *
+ * Each closure receives $request, an array with:
+ *   method         the HTTP method, as a string
+ *   requestParams  extra URL segments after the endpoint path
+ *   query          query string values: ?page=2 gives ['page' => '2']
+ *   body           the JSON body, already decoded into an array
+ *   rawBody        the body as a raw string, if you need it
+ *   headers        the request headers
+ *   config         everything from config.php
+ *
+ * Response::success($data, $code) and Response::error($message, $code) send the
+ * answer and stop the request: nothing after them runs
+ */
+
+return [
+    'get' => function (array $request) {
+        Response::success([
+            'message' => 'Endpoint is working',
+            'params'  => $request['requestParams'],
+            'query'   => $request['query'],
+        ]);
+    },
+
+    'post' => function (array $request) {
+        $body = $request['body'];
+
+        // Validate:: stops the request with a 422 when a value is missing or
+        // malformed, so the returned value is always safe to use
+        $name  = Validate::required($body['name'] ?? null, 'name');
+        $email = Validate::email($body['email'] ?? null, 'email');
+
+        Response::success([
+            'name'  => $name,
+            'email' => $email,
+        ], 201);
+    },
+];

package/src/backend/example.config.js

@@ -1,12 +1,16 @@
 "use strict";
 
 /**
- * Mirror of src/backend/example.config.php
- *
- * Copy this file to config.js and fill in real values. config.js is git-ignored and stays local.
+ * Template for config.php, which holds the real values and is git-ignored.
+ * If config.js is missing, copy this file over it.
  */
 
 module.exports = {
+
+  // Environment: "production" hides error details from anyone calling your API
+  // Switch to "debug" while you build to see full error messages
+  APP_ENV: "production",
+
   // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
   GENERAL_API_KEY: "DEFAULT_KEY",
 
@@ -30,7 +34,4 @@ module.exports = {
   DB_NAME: "example_db",
   DB_USER: "root",
   DB_PASS: "",
-
-  // Environment: 'production' hides error details; anything else = debug.
-  APP_ENV: "production",
 };

package/src/backend/example.config.php

@@ -2,12 +2,16 @@
 declare(strict_types=1);
 
 /**
- * Mirror of src/backend/example.config.php
- *
- * Copy this file to config.php and fill in real values. config.php is git-ignored and stays local.
+ * Template for config.php, which holds the real values and is git-ignored.
+ * If config.php is missing, copy this file over it.
  */
 
 return [
+
+    // Environment: 'production' hides error details from anyone calling your API
+    // Switch to 'debug' while you build to see full error messages
+    'APP_ENV' => 'production',
+
     // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
     'GENERAL_API_KEY' => 'DEFAULT_KEY',
 
@@ -30,8 +34,5 @@ return [
     'DB_HOST' => '127.0.0.1',
     'DB_NAME' => 'example_db',
     'DB_USER' => 'root',
-    'DB_PASS' => '',
-
-    // Environment: 'production' hides error details; anything else = debug.
-    'APP_ENV' => 'production',
+    'DB_PASS' => ''
 ];

package/src/backend/package.json

@@ -2,11 +2,11 @@
   "name": "backend-node",
   "version": "1.0.0",
   "private": true,
-  "description": "Node.js backend for a Nibula site. Coexists with the PHP backend; pick one at scaffold time. Front controller: _core/index.js.",
-  "main": "_core/index.js",
+  "description": "Node.js backend for a Nibula site. Coexists with the PHP backend; pick one at scaffold time. Front controller: core/index.js.",
+  "main": "core/index.js",
   "type": "commonjs",
   "scripts": {
-    "start": "node _core/index.js"
+    "start": "node core/index.js"
   },
   "engines": {
     "node": ">=18"

package/src/backend/web.config

@@ -19,13 +19,13 @@
             <rules>
 
                 <rule name="PassThroughCoreIndex" stopProcessing="true">
-                    <match url="^_core/index\.php$" ignoreCase="true" />
+                    <match url="^core/index\.php$" ignoreCase="true" />
                     <action type="None" />
                 </rule>
 
                 <rule name="RewriteToFrontController" stopProcessing="true">
                     <match url="^(.*)$" ignoreCase="true" />
-                    <action type="Rewrite" url="_core/index.php" appendQueryString="true" />
+                    <action type="Rewrite" url="core/index.php" appendQueryString="true" />
                 </rule>
 
             </rules>

package/src/frontend/hosting/.htaccess

@@ -40,7 +40,7 @@ ErrorDocument 403 /404.html
 <IfModule mod_rewrite.c>
     RewriteEngine On
     RewriteBase /
-    RewriteRule ^api/(.*)$ backend/_core/index.php [QSA,L]
+    RewriteRule ^api/(.*)$ backend/core/index.php [QSA,L]
 </IfModule>
 
 # === Static files ===========================================================

package/src/frontend/hosting/web.config

@@ -27,7 +27,7 @@
                 <!-- PHP backend: rewrite /api to the PHP front controller. -->
                 <rule name="ApiToPhp" stopProcessing="true">
                     <match url="^api/(.*)" ignoreCase="true" />
-                    <action type="Rewrite" url="backend/_core/index.php" appendQueryString="true" />
+                    <action type="Rewrite" url="backend/core/index.php" appendQueryString="true" />
                 </rule>
 
                 <!-- Node backend (requires ARR). Delete "ApiToPhp" above to use this.

package/src/frontend/layouts/base.njk

@@ -86,6 +86,9 @@
         {# Syntax highlighting for code blocks #}
         <link rel="stylesheet" href="{{ '/css/prism.css' | url }}">
 
+        {# Global CSS #}
+        <link rel="stylesheet" href="{{ '/css/global.css' | url }}"/>
+
         {# Page CSS #}
         <link rel="stylesheet" href="{{ ('/css/pages/' + title + '.css') | url }}"/>
 
@@ -116,13 +119,6 @@
         {# Bootstrap JS #}
         <script src="{{ '/js/bootstrap.bundle.min.js' | url }}" defer></script>
 
-        {# Foundation JS #}
-        {# <script src="{{ '/js/foundation.min.js' | url }}" defer></script> #}
-
-        {# UIkit JS #}
-        {# <script src="{{ '/js/uikit.min.js' | url }}" defer></script> #}
-        {# <script src="{{ '/js/uikit-icons.min.js' | url }}" defer></script> #}
-
         {# Bulma — no JS needed #}
 
         {# Per-page CDN JS #}

package/src/frontend/scss/{_global.scss → global.scss}

@@ -4,8 +4,6 @@
 // Frameworks imports
 @import "modules/frameworks/bootstrap";
 // @import "modules/frameworks/bulma";
-// @import "modules/frameworks/foundation";
-// @import "modules/frameworks/uikit";
 
 // Markdown styling. Applies to content rendered with renderFile
 @import "modules/markdown";

package/src/frontend/scss/modules/frameworks/_bootstrap.scss

@@ -5,8 +5,6 @@
 // ╚══════════════════════════════════════════════════════╝
 
 // Imports can be filtered by commenting them
-// Example:
-// @import "bootstrap/scss/example-bootstrap-module";
 
 //==========================
 // 1️⃣ CORE – Functions and variables

package/src/frontend/scss/modules/frameworks/_bulma.scss

@@ -5,8 +5,6 @@
 // ╚══════════════════════════════════════════════════════╝
 
 // Imports can be filtered by commenting them
-// Example:
-// @import "bulma/sass/example-bulma-module";
 
 //==========================
 // 1️⃣ CORE – Utilities and variables

package/src/frontend/scss/pages/404.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";
 

package/src/frontend/scss/pages/homepage.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";
 

package/tools/config/settings.json

@@ -71,19 +71,7 @@
     "styleTemplate": "template.scss",
     "routeTemplate": "template.njk",
     "layoutExtension": "njk",
-    "defaultData": {
-      "seo": {
-        "title": "{title}",
-        "description": "Description",
-        "keywords": "",
-        "noindex": false,
-        "canonical": ""
-      },
-      "cdn": {
-        "css": [],
-        "js": []
-      }
-    }
+    "dataTemplate": "template.json"
   },
   "frontMatter": {
     "title": "title: \"{camelName}\"",

package/tools/lib/pagesData.js

@@ -1,7 +1,7 @@
 const path = require('path');
 const settings = require('../config/settings.json');
 const { PATHS } = require('./paths');
-const { exists, readText, writeJson } = require('./files');
+const { exists, readText, readJson, writeJson } = require('./files');
 const { log } = require('./logger');
 const { toCamelCase, toTitleCase, formatValue } = require('./text');
 
@@ -28,7 +28,14 @@ function writePagesData(data) {
 }
 
 function createRecord(pageName) {
-    return formatValue(settings.page.defaultData, { title: toTitleCase(pageName) });
+    const templateFile = path.join(PATHS.templates, settings.page.dataTemplate);
+
+    if (!exists(templateFile)) {
+        log('page.templateMissing', { path: templateFile });
+        return null;
+    }
+
+    return formatValue(readJson(templateFile), { title: toTitleCase(pageName) });
 }
 
 function addPageData(pageName) {
@@ -41,7 +48,10 @@ function addPageData(pageName) {
         return;
     }
 
-    data[camelName] = createRecord(pageName);
+    const record = createRecord(pageName);
+    if (!record) return;
+
+    data[camelName] = record;
 
     writePagesData(data);
     log('pagesData.recordAdded', { name: camelName });

package/tools/res/templates/template.scss

@@ -1,9 +1,6 @@
 // Getting root rules from _root.scss
 @use "../root" as root; // Usage: root.$value-name
 
-// This global module contains the import framework, necessary modules for each page and any other common styles
-@import "../global";
-
 // Import any other module you need by import down here
 // @import "../modules/moduleName";
 

package/src/backend/_core/index.js

@@ -1,230 +0,0 @@
-"use strict";
-
-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;
-
-const config = loadConfig();
-
-const APP_ENV = config.APP_ENV || "production";
-
-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");
-
-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);
-}
-
-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.",
-    );
-  }
-}
-
-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 {
-    const method = req.method;
-    const parsedUrl = new URL(req.url, "http://localhost");
-    let uri = parsedUrl.pathname;
-
-    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);
-      }
-    }
-
-    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;
-      }
-
-      params.unshift(checkParts.pop());
-    }
-
-    if (!endpointFile) {
-      send404(res);
-      return;
-    }
-
-    const base = isProtected ? baseProtected : basePublic;
-    let endpointPath = endpointFile
-      .split(path.sep)
-      .join("/")
-      .replace(base.split(path.sep).join("/"), "")
-      .replace(/\.js$/, "")
-      .replace(/^\//, "");
-
-    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
-    const ip =
-      (req.headers["x-forwarded-for"] || "").split(",")[0].trim() ||
-      req.socket.remoteAddress ||
-      "";
-    RateLimiter.check(ip, 60, 60, Response, res);
-
-    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", 403);
-      }
-    }
-
-    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 (!res.writableEnded) {
-      res.end();
-    }
-  } catch (err) {
-    if (err === HALT) {
-      return;
-    }
-    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, () => {
-  console.log(
-    `[backend-node] listening on http://${HOST}:${PORT} (env: ${APP_ENV})`,
-  );
-});
-
-module.exports = server;