nibula 1.0.0

package/docs/Assistant CLI.md

@@ -0,0 +1,66 @@
+# Assistant CLI
+
+> Examples use JavaScript, but everything applies equally to TypeScript. The only difference is the file extension (`.ts` instead of `.js`), that imports do **not** include the extension, and that paths use `src/frontend/ts/` instead of `src/frontend/js/`.
+
+An interactive CLI to manage pages without touching files manually.
+
+Run it from anywhere inside a project:
+
+```
+nib cli
+```
+
+## Menu
+
+```
+1. Create page
+2. Remove page
+3. Rename page
+4. Configure output path
+```
+
+Use `CTRL/CMD + C` (or `CTRL + D`) to exit.
+
+## Create page
+
+Enter a page name in any format — the CLI converts it to kebab-case automatically.
+
+For a page named `my-page`, the following files are created:
+
+| File | Purpose |
+|---|---|
+| `src/frontend/scss/pages/myPage.scss` | SCSS entry point |
+| `src/frontend/js/pages/myPage.js` | JS entry point |
+| `src/frontend/_routes/my-page.njk` | Nunjucks template |
+
+It also adds an `elif` block in `page-components.njk` and a stub entry in `site.json`:
+
+```json
+    "myPage": {
+      "seo": {
+        "title": "My page",
+        "description": "Description",
+        "keywords": "",
+        "noindex": false,
+        "canonical": ""
+      },
+      "cdn": {
+        "css": [],
+        "js": []
+      }
+    }
+```
+
+## Remove page
+
+Deletes all source files for the page and cleans up the output directory, `page-components.njk`, and `site.json`.
+
+## Rename page
+
+Renames all three source files, updates the `elif` block in `page-components.njk`, and renames the record in `site.json` while preserving all existing fields.
+
+## Configure output path
+
+Updates the output directory across `.eleventy.js` and all relevant `package.json` scripts in one shot. The old output folder is deleted automatically.
+
+> ⚠️ `homepage` and `404` are protected — they cannot be created, removed, or renamed via the CLI.

package/docs/Backend.md

@@ -0,0 +1,151 @@
+# Backend
+
+> **PHP requirement** — the backend runs only on servers with PHP support:
+> - **Apache** (shared hosting, VPS) ✅
+> - **Nginx** + PHP-FPM (VPS) ✅
+> - **IIS** + FastCGI (Windows Server) ✅
+> - **Static hosting** (Netlify, Vercel, GitHub Pages, Cloudflare Pages) ❌
+
+The backend is a PHP REST API located in `src/backend/`, copied to the output directory automatically at build time.
+
+## Structure
+
+```
+src/backend/
+├── api/
+│   └── protected/    # Endpoints requiring X-Api-Key header
+│   ├── public/       # Endpoints accessible without an API key
+├── _core/            # Framework internals (routing, modules) — do not edit
+│   └── modules/      # Response, RateLimiter, ...
+├── database/
+│   ├── Database.php
+│   └── migrations/
+├── example.config.php   # Template — versioned, safe to commit
+└── config.php           # Your local config, generated on setup — never commit this
+```
+
+> A scaffolded project contains **both** files. `config.php` is generated automatically by `nib new` (a copy of the example) and is git-ignored, so your secrets stay local and are never pushed. `example.config.php` is kept and versioned: it's the file that ends up on GitHub, acting as a secret-free reference so anyone cloning the project knows which keys to set. If `config.php` is ever missing (e.g. after a fresh clone), just copy `example.config.php` to `config.php`.
+
+> Note: in the boilerplate repo itself, only `example.config.php` exists — `config.php` is created at scaffold time, not shipped.
+
+## Configuration
+
+`config.php` works like a `.env` file — it holds secrets and environment settings that stay local and out of version control.
+
+Fill in your values:
+
+### config.php <small>(`src/backend/`)</small>
+```php
+// Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
+'GENERAL_API_KEY' => 'DEFAULT_KEY',
+
+// If you want restrict access to protected endpoints to specific clients, you can define custom keys for each endpoint
+// For subfolder endpoints, use the relative path ('subfolder/endpoint')
+'CUSTOM_ENDPOINT_KEYS' => [
+    'subfolder/endpoint'    => 'custom-key',
+],
+
+'GENERAL_ALLOWED_ORIGINS' => [
+    '*',
+    // 'https://example.com',
+],
+
+'CUSTOM_ENDPOINT_ORIGINS' => [
+    'subfolder/endpoint'    => ['https://app.example.com'],
+],
+
+// Database configuration
+'DB_HOST' => '127.0.0.1',
+'DB_NAME' => 'example_db',
+'DB_USER' => 'root',
+'DB_PASS' => '',
+```
+
+### API keys
+
+`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use `CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for subfolder endpoints, use the relative path as the key.
+
+> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only for server-to-server calls over HTTPS. Never embed it in frontend code, where it would be publicly visible.
+
+### CORS (allowed origins)
+
+Cross-origin access mirrors the API-key model:
+
+- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any endpoint from a browser.
+- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint, keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
+
+Origins must be exact (scheme + host, no trailing slash), e.g. `https://example.com`. When a request's `Origin` is in the resolved list, it is reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty list sends no CORS header — the most restrictive setting; same-origin requests still work. Use `'*'` as the only element to allow any origin (not recommended for protected endpoints).
+
+Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise `GENERAL_ALLOWED_ORIGINS`.
+
+## How routing works
+
+The file path inside `api/` maps directly to the URL. Extra URL segments become route parameters available as `$requestParams[]`.
+
+Every endpoint file has access to:
+
+| Variable | Description |
+|---|---|
+| `$method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
+| `$requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
+
+## Creating a public endpoint
+
+Create a `.php` file anywhere inside `api/public/`
+
+### api/public/example.php
+```php
+<?php
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+
+if ($method !== 'GET') {
+    Response::error('Method not allowed', 405);
+}
+
+$id = isset($requestParams[0]) ? (int)$requestParams[0] : null;
+
+Response::success(['id' => $id]);
+```
+
+## Creating a protected endpoint
+
+Create a `.php` file inside `api/protected/`. The API key check happens automatically before your file runs.
+
+### api/protected/example.php
+```php
+<?php
+declare(strict_types=1);
+
+require_once CORE_PATH . '/modules/Response.php';
+
+if ($method !== 'GET') {
+    Response::error('Method not allowed', 405);
+}
+
+Response::success(['visits' => 1024]);
+```
+
+To assign a dedicated key, add it to `config.php`:
+
+```php
+'CUSTOM_ENDPOINT_KEYS' => [
+    'endpoint' => 'custom-key',
+],
+```
+
+## The Response helper
+
+```php
+Response::success($data, $code);            // default 200
+Response::error($message, $code, $details); // default 400
+Response::noContent();                      // 204
+```
+
+## Pre-built endpoints
+
+| Route | Method | Description |
+|---|---|---|
+| `/api/public/example-public` | `GET` | Example endpoint that doesn't require any key |
+| `/api/protected/example-protected` | `GET` | Example endpoint that requires X-API-KEY |

package/docs/Components.md

@@ -0,0 +1,96 @@
+# Nunjucks (HTML) Components
+
+## What is Nunjucks
+
+Nunjucks (`.njk`) is an HTML file that supports logic like variables, `if` statements, and `for` loops. It can extend a base layout and include other `.njk` components
+
+## Create a component
+
+Create a new `.njk` file anywhere inside `src/frontend/components/`. You can organize them into subfolders freely
+
+```
+src/frontend/components/
+├── global/
+├── layouts/
+├── modals/
+│   └── privacyModal.njk # You can move it to a modals/subfolder
+├── welcome.njk
+```
+
+## Include a component
+
+To render a component inside a page, navigate to `src/frontend/layouts/` and edit `page-components.njk`
+
+### page-components.njk <small>(`src/frontend/layouts/`)</small>
+
+```js
+{% if title == "homepage" %}
+{% include "welcome.njk" %}
+
+{% elif title == "examplePage" %}
+{% include "exampleComponent1.njk" %}
+{% include "subfolder/exampleComponent2.njk" %}
+
+{% else %}
+{% include "404/_404.njk" %}
+{{ content | safe }}
+{% endif %}
+```
+
+Add a new `{% elif %}` block for each page, listing its components in order. If a component lives in a subfolder, specify the relative path accordingly
+
+> ⚠️ A new `elif` block is automatically added when you create a page via the Assistant CLI
+
+> ⚠️ If you move or delete a component, always update `page-components.njk` or the site will break
+
+### Using Markdown files in components
+
+You can also render a `.md` file directly inside any `.njk` component using the `mdFile` shortcode:
+
+```njk
+{% mdFile "docs/your-file.md" %}
+```
+
+The path is relative to the project root (where `.eleventy.js` lives).
+
+> ⚠️ The file is read at build time — changes to the `.md` file trigger a rebuild in watch mode.
+
+## Nest components
+
+A component can include other components. This is useful for breaking complex sections into smaller, reusable pieces.
+
+### exampleComponent.njk
+```js
+<section class="hero">
+  {% include "ui/heroTitle.njk" %}
+  {% include "ui/heroButton.njk" %}
+</section>
+```
+
+> The same path rules apply: if the included component is in a subfolder, specify the full relative path.
+
+## Global components
+
+Header and footer live in `src/frontend/components/global/` and are automatically included in every page via `base.njk`. Edit them to change the site-wide layout
+
+## Site data in components
+
+All values defined in `src/frontend/data/site.json` are globally available in every component via `{{ site.* }}`
+
+### site.json <small>(`src/data/`)</small>
+```json
+{
+  "title": "My Site",
+  "logo": "/img/logo.png",
+  "legal": {
+    "privacy": "/privacy"
+  }
+}
+```
+
+### Usage in any `.njk` file
+```js
+<p>{{ site.title }}</p>
+<a href="{{ site.legal.privacy }}">Privacy Policy</a>
+<img src="{{ site.logo }}" alt="{{ site.title }}">
+```

package/docs/Creating pages.md

@@ -0,0 +1,65 @@
+# Creating Pages
+
+> Examples use JavaScript, but everything applies equally to TypeScript. The only difference is the file extension (`.ts` instead of `.js`), that imports do **not** include the extension, and that paths use `src/frontend/ts/` instead of `src/frontend/js/`.
+
+The recommended way is via the **Assistant CLI**
+
+## What gets created
+For a page named `my-page`:
+
+| File | Purpose |
+|---|---|
+| `src/frontend/_routes_/my-page.njk` | Template with front matter |
+| `src/frontend/scss/pages/myPage.scss` | Imports framework + modules |
+| `src/frontend/js/pages/myPage.js` | Imports JS modules |
+
+## Adding content
+
+1. Create a component in `src/frontend/components/` (e.g. `_myPage.njk`)
+2. Include it in `src/frontend/layouts/page-components.njk` inside the generated `elif` block:
+
+```njk
+{% elif title == "myPage" %}
+  {% include "_myPage.njk" %}
+```
+
+See **Components** DOC file for more info
+
+## URL and title
+
+The URL is the kebab-case name (`/my-page/`). The `title` in the front matter is camelCase (`myPage`) and is used internally to load the correct CSS and JS files — do not change it.
+
+## Subpages (nested URLs)
+
+To create a URL like `domain.it/about/team`, edit the `permalink` in `src/frontend/_routes/team.njk` and add the parent segment before the final slash:
+
+```njk
+---
+title: "team"
+permalink: "about/team/"
+layout: page-components.njk
+---
+```
+
+The parent path (`about`) does **not** need to exist as a real page — it's just a URL prefix. Only the last segment (`team`) must match the filename and the `title` in the front matter.
+
+| Goal URL | permalink value | File |
+|---|---|---|
+| `/team/` | `/team/` | `_routes/team.njk` |
+| `/about/team/` | `/about/team/` | `_routes/team.njk` |
+| `/company/about/team/` | `/company/about/team/` | `_routes/team.njk` |
+
+## SEO
+
+The CLI creates a stub entry in `src/frontend/data/site.json`. Fill it in:
+
+```json
+"myPage": {
+  "seo": {
+    "title": "My Page | Site Name",
+    "description": "Page description"
+  }
+}
+```
+
+See **Head & SEO** for all available options.

package/docs/Deploy.md

@@ -0,0 +1,101 @@
+# 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.
+
+## Where to publish
+
+### Shared hosting (Apache — e.g. Aruba, most cPanel providers)
+
+The most common and beginner-friendly option. You rent space on a server that's
+already set up, and you just upload your files.
+
+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.
+
+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).
+
+> 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.
+
+### 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.
+
+---
+
+## 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.
+
+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
+
+This is the config that makes shared hosting like Aruba work out of the box.
+
+## 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.
+
+Covers the same rules as the Apache configuration above.
+
+## 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.
+
+**`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.
+
+They provide:
+- `server_tokens off` — hides the Nginx version
+- `autoindex off` — disables directory listing
+- 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
+- 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.
+
+### 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:
+
+| 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` |

package/docs/Head and SEO.md

@@ -0,0 +1,117 @@
+# Head & SEO
+
+Global settings live in `src/frontend/data/site.json` and are available everywhere via `{{ site.* }}`.
+
+## Global fields
+
+```json
+{
+  "site_name": "Site name",
+  "title": "Site title",
+  "description": "Site description",
+  "keywords": "keyword1, keyword2, keyword3",
+  "domain": "yoursite.com",
+  "url": "https://yoursite.com",
+  "lang": "en",
+  "author": "Name and surname",
+  "data_bs_theme": "dark",
+  "theme_color": {
+    "light": "#ffffff",
+    "dark": "#0d1117"
+  },
+  "favicon": "/assets/brand/favicon.svg",
+  "logo": "/assets/brand/logo.svg",
+  "legal": {
+    "privacy": "",
+    "cookie": "",
+    "cookieControls": "",
+    "terms": "",
+    "copyright": {
+      "year": "2026",
+      "text": "Copyright text"
+    }
+  }
+}
+```
+
+| Field | Purpose |
+|---|---|
+| `site_name` | Brand name (used in meta tags and JSON-LD) |
+| `title` | Default page title — fallback when a page has no `seo.title` |
+| `description` | Default meta description — fallback for pages |
+| `keywords` | Default meta keywords — fallback for pages |
+| `domain` / `url` | Canonical URLs, `og:url`, JSON-LD |
+| `lang` | HTML `lang` attribute |
+| `author` | Meta author and JSON-LD author |
+| `data_bs_theme` | Bootstrap color scheme (`light` / `dark`) |
+| `theme_color` | Browser UI / PWA color, per scheme (`light` / `dark`) |
+| `favicon` | Path to the favicon |
+| `logo` | Path to the logo, also used as social image |
+| `legal.privacy` / `cookie` / `cookieControls` / `terms` | Legal page URLs |
+| `legal.copyright.year` / `text` | Footer copyright |
+
+## Per-page SEO and CDN
+
+Each page is keyed by its camelCase `title` from the front matter:
+
+```json
+"pages": {
+  "examplePage": {
+    "seo": {
+      "title": "Example Page",
+      "description": "Description",
+      "keywords": "",
+      "noindex": false,
+      "canonical": ""
+    },
+    "cdn": {
+      "css": ["https://example.com/lib.min.css"],
+      "js": ["https://example.com/lib.min.js"]
+    }
+  }
+}
+```
+
+| Field | Purpose | If empty / absent |
+|---|---|---|
+| `seo.title` | Page title | Falls back to global `title` |
+| `seo.description` | Meta description | Falls back to global `description` |
+| `seo.keywords` | Meta keywords | Falls back to global `keywords` |
+| `seo.noindex` | If `true`, emits `<meta name="robots" content="noindex, follow">` and drops the page from the sitemap | Page is indexable |
+| `seo.canonical` | Absolute canonical URL override | Computed as `url + page.url` |
+| `cdn.css` / `cdn.js` | Extra per-page CDN links | No extra links loaded |
+
+## Fallback logic
+
+Global values are defaults, not duplicates. A page value is used when present; otherwise the global one applies:
+
+```njk
+{{ pageData.seo.title or title or site.title }}
+{{ pageData.seo.description or site.description }}
+{{ pageData.seo.keywords or site.keywords }}
+```
+
+`noindex` and `canonical` have no global default: `noindex` defaults to indexable behavior, `canonical` is computed from the URL. They exist per-page only.
+
+## theme_color
+
+Two tags are emitted so the browser bar follows the user's system scheme:
+
+```njk
+<meta name="theme-color" content="{{ site.theme_color.light }}" media="(prefers-color-scheme: light)">
+<meta name="theme-color" content="{{ site.theme_color.dark }}" media="(prefers-color-scheme: dark)">
+```
+
+This is independent from `data_bs_theme`, which controls the Bootstrap theme, not the browser UI.
+
+## AI & SEO bots
+
+`llms.txt`, `robots.txt` and `sitemap.xml` are generated from `.njk` templates and are publicly reachable (they must not be blocked by the server config).
+
+| File | Purpose | Reachable at |
+|---|---|---|
+| `llms.njk` | Tells AI models what the site is about | `yoursite.com/llms.txt` |
+| `robots.njk` | Controls search-engine crawling | `yoursite.com/robots.txt` |
+| `sitemap.njk` | Lists indexable pages (skips drafts, 404, and `noindex`) | `yoursite.com/sitemap.xml` |
+
+To customize, edit `src/frontend/llms.njk` or `src/frontend/robots.njk` directly.

package/docs/Javascript.md

@@ -0,0 +1,53 @@
+# JavaScript
+
+> Examples use JavaScript, but everything applies equally to TypeScript. The only difference is the file extension (`.ts` instead of `.js`), that imports do **not** include the extension, and that paths use `src/frontend/ts/` instead of `src/frontend/js/`.
+
+## Page JS
+
+Each page has its own JS entry point in `src/frontend/js/pages/`, bundled and minified by esbuild and loaded automatically by `base.njk`.
+
+Import only what the page needs.
+
+### examplePage.js <small>(`src/frontend/js/pages/`)</small>
+
+```js
+// import { initExampleModule } from '../modules/exampleModule.js';
+
+document.addEventListener("DOMContentLoaded", () => {
+    // initExampleModule();
+});
+
+// Page logic here
+```
+
+## Modules
+
+Modules live in `src/frontend/js/modules/`. Modules that interact with the DOM must be called inside `DOMContentLoaded`; others can be called anywhere.
+
+## Adding a module
+
+Create a new `.js` file in `src/frontend/js/modules/`. Subfolders are allowed.
+
+Use ESM syntax — esbuild handles the bundling:
+
+### exampleModule.js <small>(`src/frontend/js/modules/`)</small>
+
+```js
+export function exampleModule() {
+    // Module logic here
+}
+```
+
+Then import it in the pages that need it:
+
+```js
+import { exampleModule } from '../modules/exampleModule.js';
+```
+
+In TypeScript, omit the extension:
+
+```ts
+import { exampleModule } from '../modules/exampleModule';
+```
+
+> ⚠️ Files inside `_tools/` run directly in Node.js without a bundler — use CommonJS (`require` / `module.exports`) there, not ESM.