nibula 2.4.2 → 2.4.4

package/docs/Backend.md

@@ -1,219 +0,0 @@
-# Backend
-
-Nibula ships **two interchangeable backends** — PHP and Node.js. You pick one
-when you scaffold a project with `nib new`, and **only that one is copied into
-your project**: a Node project contains no PHP files and vice versa. Shared,
-backend-agnostic files (SQL migrations, `.htaccess`, `web.config`) are always
-included.
-
-Both provide the same REST API: same routing, same `Response` envelope, same
-`X-Api-Key` auth, same CORS model, same rate limiter. Only the syntax differs.
-
-> **The examples below are in JavaScript (the Node backend).** If you chose PHP,
-> everything works exactly the same way — same routing, same variables, same
-> `Response` helper, same behaviour. Only the syntax differs.
-
-For **where each backend can run** and how to deploy it, see `docs/Deploy.md`.
-
-## Structure
-
-The tree below shows both backends for reference; your project will have only
-one side of each pair.
-
-```
-src/backend/
-├── api/
-│   ├── public/       # Endpoints accessible without an API key
-│   └── protected/    # Endpoints requiring the X-Api-Key header
-├── _core/            # Framework internals (routing, modules) — do not edit
-│   ├── index.php     # PHP front controller           (PHP project)
-│   ├── index.js      # Node front controller + server (Node project)
-│   ├── init.php / init.js
-│   └── modules/      # Response, RateLimiter
-├── database/
-│   ├── Database.php  # PDO singleton                  (PHP project)
-│   ├── Database.js   # mysql2 pool singleton          (Node project)
-│   └── migrations/   # shared
-├── example.config.php / example.config.js   # versioned template
-└── config.php / config.js                   # generated on setup, never commit
-```
-
-> `config.php` / `config.js` are created automatically by `nib new` as a copy of
-> the matching `example.config.*`, and are git-ignored so your secrets stay
-> local. If `config.*` is missing (e.g. after a fresh clone), copy the example.
-
-### Installing Composer packages (PHP)
-
-Backend dependencies live in `src/backend/_core`, next to `composer.json`.
-Install from there, not from the project root:
-
-```bash
-cd src/backend/_core
-composer require vendor/package
-```
-
-`_core/init.php` already requires Composer's autoloader, so an installed package
-is usable in your endpoints straight away — there is no extra `require` to add.
-
-Packages land in `src/backend/_core/vendor/`, which is git-ignored. After a fresh
-clone that folder is missing and the backend won't start at all: run
-`composer install` from `src/backend/_core` to restore it.
-
-## How routing works
-
-The file path inside `api/` maps directly to the URL. The `public` / `protected`
-folder does **not** appear in the URL — it only decides whether the `X-Api-Key`
-check applies:
-
-- `api/public/example-public` → `/api/example-public` (no key)
-- `api/protected/example-protected` → `/api/example-protected` (requires key)
-
-Subfolders **do** appear: `api/public/users/list` → `/api/users/list`.
-
-Extra URL segments become route parameters, resolved from the deepest match
-backwards: `/api/posts/42` looks for `posts/42` first, then falls back to
-`posts` with `42` as a parameter.
-
-Every endpoint receives:
-
-| Field | Description |
-|---|---|
-| `method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
-| `requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
-
-The Node handler also gets `query`, `body` (parsed JSON), `rawBody`, `headers`,
-`config`, `req`, `res`.
-
-> ⚠️ If two files share the same path — one in `public/`, one in `protected/` —
-> the public one wins, so the endpoint ends up **without** authentication. Don't
-> duplicate names across the two folders.
-
-## Creating an endpoint
-
-Create a file anywhere inside `api/public/` or `api/protected/`. For protected
-endpoints the API-key check runs automatically before your file does.
-
-```js
-module.exports = ({ method, requestParams, Response }) => {
-    if (method !== 'GET') Response.error('Method not allowed', 405);
-    const id = requestParams[0] ? parseInt(requestParams[0], 10) : null;
-    Response.success({ id });
-};
-```
-
-## The Response helper
-
-Same envelope in both backends.
-
-```js
-Response.success(data, code);            // default 200
-Response.error(message, code, details);  // default 400
-Response.noContent();                    // 204
-```
-
-Shapes:
-
-- success → `{ "status": "success", "data": ... }`
-- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
-
-## Configuration
-
-`config.php` / `config.js` work like a `.env` file: they hold secrets and
-environment settings that stay local and out of version control. Same keys in
-both, PHP-array vs JS-object syntax.
-
-```js
-module.exports = {
-    // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
-    GENERAL_API_KEY: 'DEFAULT_KEY',
-
-    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
-    // For subfolder endpoints, use the relative path ('subfolder/endpoint')
-    CUSTOM_ENDPOINT_KEYS: {
-        'subfolder/example-protected': 'custom-key',
-    },
-
-    GENERAL_ALLOWED_ORIGINS: [
-        '*',
-        // 'https://example.com',
-    ],
-
-    CUSTOM_ENDPOINT_ORIGINS: {
-        'subfolder/example-protected': ['https://app.example.com'],
-    },
-
-    // Database configuration
-    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',
-};
-```
-
-### API keys
-
-`GENERAL_API_KEY` is the fallback for all protected endpoints.
-`CUSTOM_ENDPOINT_KEYS` assigns a different key to a specific endpoint, keyed by
-its relative path (`'subfolder/endpoint'`).
-
-> ⚠️ The 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
-
-Mirrors the API-key model: `GENERAL_ALLOWED_ORIGINS` is the default list,
-`CUSTOM_ENDPOINT_ORIGINS` overrides it per endpoint using the same relative path.
-
-Origins must be exact (scheme + host, no trailing slash). A matching `Origin` is
-reflected in `Access-Control-Allow-Origin` with `Vary: Origin`. An empty list
-sends no CORS header — the most restrictive setting; same-origin requests still
-work. `'*'` as the only element allows any origin (not recommended for protected
-endpoints).
-
-Resolution order: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise
-`GENERAL_ALLOWED_ORIGINS`.
-
-### Error verbosity
-
-`APP_ENV` decides what an unhandled exception tells the client.
-
-| Value | Response to a 500 |
-|---|---|
-| `'production'` (default) | `{"status":"error","message":"Internal server error","code":500}` |
-| anything else | the real exception message, plus `stack` (Node) or `file` and `line` (PHP) |
-
-On PHP it does one extra thing: `'production'` also turns off `display_errors`
-and `error_reporting`, so a stray warning can't be printed before the JSON and
-corrupt the response body.
-
-Set it to something like `'development'` while building, and back to
-`'production'` before you publish. Missing key means `'production'`.
-
-> This is a config key, **not** an environment variable. Setting `APP_ENV` in a
-> shell or in a systemd unit has no effect — both backends read it from
-> `config.js` / `config.php` only.
-
-## Database
-
-Both backends expose a connection singleton reading the same config —
-`database/Database.js` (a `mysql2` pool) or `database/Database.php` (a PDO
-singleton).
-
-```js
-const pool = Database.getInstance();
-const [rows] = await pool.execute(sql, params);
-```
-
-`mysql2` is installed at scaffold time and loaded lazily, so the backend boots
-fine without a database.
-
-## Pre-built endpoints
-
-| Route | Method | Description |
-|---|---|---|
-| `/api/example-public` | `GET` | Example endpoint requiring no key |
-| `/api/example-protected` | `GET` | Example endpoint requiring `X-Api-Key` |

package/docs/Components.md

@@ -1,236 +0,0 @@
-# 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/
-│   ├── header.njk
-│   └── footer.njk
-├── not-found.njk
-├── welcome.njk
-```
-
-## Include a component
-
-Components are included in the page that renders them. Open the page's file in `src/frontend/routes/` and write the includes in its body
-
-### example-page.njk <small>(`src/frontend/routes/`)</small>
-
-```js
----
-title: "examplePage"
-permalink: "/example-page/"
-layout: base.njk
----
-
-{% include "example-component-1.njk" %}
-{% include "subfolder/example-component-2.njk" %}
-```
-
-Components render in the order you list them. If a component lives in a subfolder, specify the relative path accordingly
-
-Paths are resolved from `src/frontend/components/`, so you never write that part — `"welcome.njk"`, not `"components/welcome.njk"`
-
-> ⚠️ If you move or delete a component, update every route that includes it or the build will fail
-
-Writing HTML directly in the route works too, and is perfectly fine for a short page. Components are the recommendation when there is something to reuse or when a page grows past a screenful — not a rule
-
-## Nest components
-
-A component can include other components. This is useful for breaking complex sections into smaller, reusable pieces.
-
-### exampleComponent.njk
-```html
-<section class="hero">
-  {% include "hero/hero-title.njk" %}
-  {% include "hero/hero-button.njk" %}
-</section>
-```
-
-> The same path rules apply: if the included component is in a subfolder, specify the full relative path.
-
-## Markdown files
-
-### What is Markdown
-
-Markdown (`.md`) is a way to write formatted text without HTML tags. You write
-`**bold**` instead of `<strong>bold</strong>`, and a line starting with `-`
-becomes a list item. For a page that is mostly text — an article, a privacy
-policy, a changelog — it is much faster than writing the markup by hand.
-
-### Write the file
-
-Create a `.md` file in `src/frontend/components/`, next to your `.njk` ones.
-
-#### article.md <small>(`src/frontend/components/`)</small>
-
-```markdown
-## Section title
-
-Regular paragraph text. **Bold** and *italic* work as usual.
-
-- First item
-- Second item
-```
-
-### Show it in a page
-
-Open the page's file in `src/frontend/routes/` and add this line to its body:
-
-```html
-<article class="markdown-body">
-    {% renderFile "article.md" | markdownPath, { site: site }, "md" %}
-</article>
-```
-
-Four parts to it:
-
-| Part | What it does |
-|---|---|
-| `class="markdown-body"` | the wrapper that applies the Markdown styling — without it your content renders unstyled |
-| `renderFile` | turns the Markdown into HTML and puts it in the page |
-| `markdownPath` | fills in the `src/frontend/components/` part of the path for you |
-| `{ site: site }` | hands the file your site settings — see below |
-| `"md"` | specifies that the rendering should be done as Markdown, ignoring the njk engine associated by default with the file extension |
-
-Subfolders work the same way as with components:
-`"legal/privacy.md" | markdownPath`
-
-### Why `{ site: site }`
-
-A `.md` file can use site values, exactly like a component:
-
-```markdown
-Welcome to {{ site.title }}
-```
-
-But a Markdown file does not automatically see them. Anything the file needs has
-to be listed in the curly braces:
-
-```js
-{% renderFile "article.md" | markdownPath, { site: site, pages: pages } %}
-```
-
-If you forget, nothing breaks — the value simply comes out empty. So if a
-`{{ site.something }}` disappears from your page, this is why.
-
-### Extras you get for free
-
-**Links to a section.** Every `##` and `###` heading gets an anchor, so you can
-link straight to it: `yoursite.com/my-page/#section-title`.
-
-**CSS classes.** Markdown produces plain HTML with no classes, so your framework's
-styling doesn't reach it. Add a class in curly braces after the element:
-
-```markdown
-## Section title {.text-center}
-```
-
-> ⚠️ If the `.md` file is missing or the name is misspelled, the build stops with
-> an error. That is on purpose: silently skipping content you asked for is worse.
-
-## 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
-
-## Custom layouts
-
-`base.njk` is the default layout, but it isn't the only one you can have. Any
-`.njk` file in `src/frontend/layouts/` is a layout, and each route picks its own.
-
-The usual reason is a page that doesn't fit the standard shell: a landing page
-with no header or footer, a full-screen login, a "coming soon" holding page.
-
-Copy `base.njk`, rename it, and change only what you need — that way you keep the
-head, the SEO tags and the CSS/JS wiring, which is the part you don't want to
-rewrite:
-
-```
-src/frontend/layouts/
-├── base.njk
-└── custom.njk
-```
-
-### custom.njk <small>(`src/frontend/layouts/`)</small>
-
-Same as `base.njk`, without the two global includes:
-
-```html
-<body>
-    <main>
-        {{ content | safe }}
-    </main>
-</body>
-```
-
-Then point the route at it:
-
-### landing.njk <small>(`src/frontend/routes/`)</small>
-
-```js
----
-title: "landing"
-permalink: "/landing/"
-layout: custom.njk
----
-```
-
-Paths are resolved from `src/frontend/layouts/`, so you write `"custom.njk"`, not
-`"layouts/custom.njk"` — the same rule as components.
-
-> ⚠️ A layout you copy is a copy: a later fix to `base.njk` won't reach it. Keep
-> the differences to the minimum, and check your custom layouts when you change
-> something in the head.
-
-## 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/frontend/data/`)</small>
-```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",
-  "logo": "/assets/brand/logo.svg",
-  "legal": {
-    "privacy": "",
-    "cookie": "",
-    "terms": "",
-    "copyright": {
-      "year": "2026",
-      "text": "All rights reserved."
-    }
-  }
-}
-```
-
-`legal.privacy`, `legal.cookie` and `legal.terms` hold the URLs of your legal pages — the footer links to them. See **Head & SEO** DOC file for what every field does
-
-### Usage in any `.njk` file
-```html
-<p>{{ site.title }}</p>
-<a href="{{ site.legal.privacy }}">Privacy Policy</a>
-<img src="{{ site.logo }}" alt="{{ site.title }}">
-```
-
-> In a `.md` file rendered with `renderFile`, these values only work if you passed
-> `site` in the curly braces — see *Why `{ site: site }`* above.
-
-## Your own data files
-
-`site.json` isn't special: **any** `.json` file you drop in `src/frontend/data/` becomes a global variable, and the variable takes the name of the file.
-
-Create `test.json`, put anything you want inside it, and every key is reachable as `test.yourKey` — no import, no configuration, no restart.

package/docs/Creating pages.md

@@ -1,52 +0,0 @@
-# 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/TS modules |
-
-It also adds a stub entry in `src/frontend/data/pages.json` for the page's SEO and CDN links — fill it in as described in the **Head & SEO** DOC file.
-
-## Adding content
-
-The route is created empty, with two commented examples: one for including a
-`.njk` component, one for rendering a `.md` file. Uncomment the one you need or
-write your HTML directly in the body — see the **Components** DOC file.
-
-## 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, and to look up the page's record in `pages.json` — do not change it.
-
-## Layout
-
-`layout` decides the HTML skeleton the page is rendered into. New pages get `base.njk`, which brings the head, the SEO tags, the header and the footer.
-
-A page that needs a different shell — a landing page with no header, for instance — points at a layout of its own. See **Components** DOC file, *Custom layouts*.
-
-## 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:
-
-```js
----
-title: "team"
-permalink: "/about/team/"
-layout: base.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` |