radix-cms 0.1.0 → 1.0.0

package/docs/CMS_CODE_GUIDE.md

@@ -0,0 +1,372 @@
+# Radix CMS: Beginner's Code Guide
+
+This guide explains how the current Radix CMS works by following the code from
+startup to a browser request. It describes what the code does today; it is not
+an architectural proposal for a future plugin system.
+
+## 1. The short version
+
+Radix is a Node.js application written in TypeScript.
+
+- **Node.js** runs JavaScript/TypeScript code on the server.
+- **Express** receives HTTP requests and chooses what code handles each URL.
+- **MySQL/MariaDB** stores pages, users, and settings.
+- **EJS** creates HTML from templates.
+- **TypeScript** is compiled from `src/` into JavaScript in `dist/`.
+- **The browser** receives HTML, CSS, JavaScript, and uploaded images.
+
+The application has two related parts:
+
+1. The **public site**, where a URL such as `/about` displays a page.
+2. The **admin site**, where authorized users manage pages, users, media, themes,
+   settings, and updates under `/admin`.
+
+## 2. Important folders
+
+```text
+src/
+  app.ts                 Application entry point and Express setup
+  routes/
+    index.ts             Public page routes
+    admin.ts             Admin, login, setup, and management routes
+  config/db.ts           MySQL connection pool wrapper
+  init/                  Database installation and initialization
+  middleware/auth.ts     Reusable role-checking middleware
+  utils/                 Settings, theme, update, and plugin helpers
+  types/                 TypeScript type declarations
+  plugins/               Example plugin code (not currently auto-loaded)
+  sql/                   Database schema SQL
+
+views/
+  themes/                Public EJS page templates
+  pages/                 Static EJS page overrides
+  admin/                 Admin EJS screens
+  defaults/              Error pages
+  layouts/               Layout templates (not all routes currently use this)
+
+public/
+  css/                   Browser CSS
+  uploads/               Uploaded media files
+
+dist/                    Compiled output generated by the build
+package.json             Dependencies and run commands
+.env                    Local configuration and secrets
+```
+
+Do not edit `dist/` directly. It is generated from `src/`. Do not commit `.env`
+or put passwords/API keys in source code.
+
+## 3. How the application starts
+
+The scripts in `package.json` are:
+
+- `npm run dev`: runs `src/app.ts` through `tsx` and watches for changes.
+- `npm run build`: compiles TypeScript into `dist/` and copies the SQL file.
+- `npm start`: compiles, then runs `dist/app.js`.
+- `npm run app`: runs the already-compiled `dist/app.js`.
+
+The startup path is:
+
+1. `src/app.ts` imports Express, sessions, routers, and database initialization.
+2. Express is created with `const app = express()`.
+3. EJS is selected as the view engine.
+4. JSON and HTML form-body parsing middleware is enabled.
+5. A session middleware is enabled. The logged-in user is stored in the session.
+6. Static folders are exposed:
+   - `/...` can serve files in `public/`.
+   - `/themes/...` serves theme assets.
+   - `/uploads/...` serves uploaded media.
+7. The admin router is mounted at `/admin`.
+8. The public router is mounted at `/`.
+9. `startServer()` initializes the database and starts listening on `SITE_PORT`
+   (normally port 3000).
+
+In Express, `app.use('/admin', adminRoutes)` means that a route written as
+`router.get('/pages', ...)` inside `admin.ts` is reached at `/admin/pages`.
+
+## 4. What happens when someone visits a public page
+
+Public routes are in [`src/routes/index.ts`](../src/routes/index.ts).
+
+### Request flow
+
+1. The request reaches the router mounted at `/`.
+2. `/` is treated as the slug `home`.
+3. `/:slug` handles URLs such as `/about` or `/hello`.
+4. `renderPageBySlug()` first checks `views/pages/<slug>.ejs`.
+5. If that file exists, it is rendered immediately. This is a **static override**.
+6. Otherwise, the code queries the `pages` database table by slug.
+7. If no row exists, the 404 template is rendered.
+8. The page's status, publish date, and minimum role are checked.
+9. The selected theme/template is resolved.
+10. EJS renders the theme with the database page and current user as variables.
+
+The database page contains fields such as:
+
+- `title`: heading and browser title
+- `slug`: URL part, such as `about`
+- `content`: HTML content, usually entered through TinyMCE
+- `template_name`: theme/template name
+- `status`: Draft, Published, Archived, and so on
+- `min_role`: minimum role allowed to view the page
+- `publish_at`: scheduled publication date
+
+### Static page override
+
+If `views/pages/about.ejs` exists, `/about` uses that file instead of the
+database row. This lets a developer create a fully custom page, but it also
+means changing the database page may appear to have no effect while the
+override file exists.
+
+### Theme rendering
+
+The default template is
+[`views/themes/default/index.ejs`](../views/themes/default/index.ejs).
+
+The route passes values into EJS, including:
+
+```text
+title
+content
+page
+user
+currentTheme
+siteName
+appVersion
+```
+
+EJS uses:
+
+- `<%= value %>` for escaped output
+- `<%- value %>` for unescaped output
+- `<% code %>` for JavaScript logic
+
+The default theme uses `<%- content %>` so saved rich-text HTML is rendered as
+HTML. This is useful for CMS content, but it makes content sanitization and
+trusted editor access important security concerns.
+
+## 5. What happens in the admin area
+
+Admin routes are in [`src/routes/admin.ts`](../src/routes/admin.ts), and the
+router is mounted at `/admin`.
+
+### Login and sessions
+
+1. `GET /admin/login` displays the login form.
+2. `POST /admin/login` looks up a user by username or email.
+3. The submitted password is compared with the stored bcrypt hash.
+4. On success, the user identity and role are placed in `req.session.user`.
+5. The browser receives a session cookie.
+6. `GET /admin/logout` destroys the session.
+
+The session is server-side state associated with a cookie. It is not the same
+thing as a user record in the database.
+
+### Role checks
+
+The roles are ordered from least to most privileged:
+
+```text
+Unregistered < Registered < Editor < Manager < Administrator
+```
+
+The admin router has its own `requireRole()` function. The reusable version is
+also in [`src/middleware/auth.ts`](../src/middleware/auth.ts).
+
+Current access pattern:
+
+- **Editor and above**: dashboard, page management, media upload, themes,
+  updates screen
+- **Administrator only**: permanent deletion, user management, settings,
+  media deletion, applying updates
+
+The role check runs before the route handler. If there is no logged-in user, it
+redirects to login. If the role is too low, it returns a 403 response.
+
+### Page management
+
+The main page operations are:
+
+| URL | Purpose |
+| --- | --- |
+| `GET /admin/pages` | List database pages and optionally filter status |
+| `GET /admin/create` | Show the create form |
+| `POST /admin/create` | Insert a new row into `pages` |
+| `GET /admin/edit/:id` | Load one page into the edit form |
+| `POST /admin/edit/:id` | Update a page row |
+| `POST /admin/delete/:id` | Mark a page as `Deleted` |
+| `POST /admin/restore/:id` | Restore a deleted page |
+| `POST /admin/permanent-delete/:id` | Permanently remove a page |
+
+The forms are EJS files under `views/admin/`. SQL parameters use `?`
+placeholders, which is the correct pattern for avoiding SQL injection from form
+values.
+
+### Media
+
+Multer handles uploads in `admin.ts`.
+
+- Files are stored in `public/uploads/`.
+- The filename is generated from the field name, timestamp, and random suffix.
+- The upload limit is 10 MB.
+- The configured extensions and MIME types are image types.
+- Files are served publicly at `/uploads/<filename>`.
+
+The media library is file-system based; media metadata is not stored in the
+database.
+
+### Settings
+
+Settings are rows in the `settings` table using a key/value design:
+
+```text
+setting_key | setting_value
+```
+
+[`src/utils/settings.ts`](../src/utils/settings.ts) loads all settings into an
+in-memory cache. `getSetting()` reads one value, and
+`clearSettingsCache()` must be called after settings are changed so a later
+request sees the new values.
+
+Some configuration is instead read from environment variables, especially
+database connection details, application version, port, and session secret.
+
+## 6. Database behavior
+
+The schema is defined in [`src/sql/radix.sql`](../src/sql/radix.sql). The main
+tables are:
+
+- `pages`: published and draft content
+- `users`: accounts, password hashes, email addresses, and roles
+- `settings`: application settings
+- `plugins`: a table reserved for plugin activation state
+- `schema_meta`: initialization and schema version markers
+
+[`src/config/db.ts`](../src/config/db.ts) creates a lazy MySQL connection pool.
+“Lazy” means the pool is created when the first query is made, not necessarily
+when the module is imported. If environment database settings change, the
+wrapper closes the old pool and creates a new one.
+
+[`src/init/dbInit2.ts`](../src/init/dbInit2.ts) is used by the current startup
+and installer flow. It:
+
+1. Reads the bundled SQL file.
+2. Removes seed `INSERT` statements before creating a new database.
+3. Checks whether the configured database exists.
+4. Creates the schema if needed.
+5. Ensures the `schema_meta` marker table exists.
+
+The admin installer writes database values to `.env`, reloads them, initializes
+the schema, and then creates the first administrator account.
+
+## 7. Installation and configuration
+
+The admin router has an installation guard. For most admin requests it checks
+whether database environment variables exist and whether `SELECT 1` succeeds.
+If not, it redirects to `/admin/install`.
+
+The installer flow is:
+
+1. `GET /admin/install` displays database settings.
+2. `POST /admin/setup/db/test` tests a connection without saving it.
+3. `POST /admin/setup/db` writes database configuration and initializes the schema.
+4. `GET /admin/setup/admin` displays the first-admin form.
+5. `POST /admin/setup/admin` creates the administrator and saves initial settings.
+6. The user is redirected to `/admin/login`.
+
+The `.env` file is loaded by `dotenv`. It is intended for per-installation
+configuration and must be protected like a password file.
+
+## 8. Themes and templates
+
+Themes live under `views/themes/`. The theme scanner in
+[`src/utils/themeScanner.ts`](../src/utils/themeScanner.ts) lists theme
+directories/files so the admin page editor can offer them in a selector.
+
+Theme CSS is served from `/themes`, while general public CSS is served from
+`public/`.
+
+A theme is an EJS template. It is not a separate Node package. A theme can:
+
+- change the page layout and navigation
+- include its own CSS/assets
+- display variables passed by the public route
+- render the page's HTML content
+
+## 9. Update checking and email
+
+`src/utils/versionCheck.ts` fetches a JSON version document from an update URL
+stored in settings (or a default remote URL). It compares the remote version
+with `APP_VERSION` and reports whether an update exists.
+
+The admin settings route uses Nodemailer for test email. SMTP values are
+stored as settings and are used to build a mail transport when a test message
+is requested.
+
+## 10. Current extension-related code
+
+There is an example under `src/plugins/my-seo-plugin/` and a type contract in
+`src/types/plugin.ts`. The proposed plugin context exposes:
+
+- the Express router
+- hook registration
+- filter registration
+- the database wrapper
+
+`src/utils/PluginManager.ts` contains hook/filter storage and a plugin loader.
+However, the current application entry point does not call `loadPlugins()`, and
+the loader's path assumptions do not line up cleanly with the compiled
+directory layout. Hooks and filters are also not currently triggered by the
+public/admin routes.
+
+Therefore, plugins are currently an unfinished extension point, not a complete
+runtime feature. For now, a custom application should use normal Express
+routes/services under `src/` and explicitly import them from `app.ts` or a
+router.
+
+## 11. A beginner's mental model for adding a feature
+
+For a feature such as a newsletter:
+
+1. **URL:** add an Express route in a router file.
+2. **Form:** add an EJS form under `views/`.
+3. **Database:** add a table or columns in SQL/migration code.
+4. **Business logic:** put validation and database operations in a service
+   module rather than making the route handler do everything.
+5. **Security:** add the appropriate role middleware and validate all input.
+6. **Assets:** put browser CSS/JavaScript in `public/` or feature-specific
+   static assets.
+7. **Startup wiring:** import and mount the router from `app.ts`.
+8. **Build:** run `npm run build`; test using the compiled application or
+   `npm run dev`.
+
+A request normally travels through this chain:
+
+```text
+Browser
+  -> Express app
+  -> middleware (body parsing, session, static files)
+  -> router
+  -> role/auth check (if needed)
+  -> route handler
+  -> database/service work
+  -> EJS template
+  -> HTML response
+```
+
+## 12. Current caveats to know before extending the CMS
+
+- `dist/` is build output and can become stale if the project is run without
+  compiling after a source change.
+- Public page rendering has a static-file override that takes priority over
+  database content.
+- The default theme renders stored content unescaped.
+- There are two role-checking implementations; future changes should consolidate
+  them to avoid behavior drifting.
+- The plugin manager is present but not fully wired into startup or request
+  events.
+- `views/layouts/admin-layout.ejs` exists, but the admin pages currently use
+  header/footer includes directly.
+- Database initialization deliberately strips seed data when creating a new
+  database, so the installed database may not contain the sample rows in the
+  checked-in SQL dump.

package/docs/CMS_USER_GUIDE.md

@@ -0,0 +1,344 @@
+# Radix CMS User Guide
+
+This guide explains how to use the current Radix CMS through the web
+interface, and how to create templates and static pages as a developer.
+
+## 1. Getting started
+
+### Start the application
+
+From the project folder:
+
+```powershell
+npm run dev
+```
+
+Open:
+
+- Public site: `http://localhost:3000/`
+- Administration: `http://localhost:3000/admin`
+
+The port comes from `SITE_PORT` in `.env`.
+
+### First installation
+
+If the database is not configured, open `/admin/install`. The installer:
+
+1. Tests the MySQL/MariaDB connection.
+2. Saves the database settings to `.env`.
+3. Creates the database schema.
+4. Creates the first administrator account.
+5. Redirects to the login page.
+
+The `.env` file contains passwords and API keys. Keep it private and do not
+commit it to source control.
+
+## 2. Log in and understand permissions
+
+Go to `/admin/login` and sign in with a user account.
+
+Roles are ordered from least to most powerful:
+
+```text
+Unregistered < Registered < Editor < Manager < Administrator
+```
+
+Current permissions are:
+
+| Role | Typical access |
+| --- | --- |
+| Unregistered | Public pages only |
+| Registered | Pages requiring registered-user access |
+| Editor | Dashboard, create/edit pages, upload media, view themes and updates |
+| Manager | Same route access as Editor in the current implementation |
+| Administrator | All Editor features plus users, settings, media deletion, and applying updates |
+
+A page's **Minimum Access Role** controls who may view a database-backed dynamic
+page. The visitor must be logged in with that role or a higher role.
+
+## 3. Create a dynamic page
+
+A dynamic page is stored in the `pages` database table. Its content, status,
+access level, and selected template can be changed through the admin interface.
+
+1. Log in as an Editor or Administrator.
+2. Open **Pages**.
+3. Click **Create New Page**.
+4. Enter a **Title**, such as `Members Area`.
+5. Enter a unique **Slug**, such as `members`.
+   - The page URL will be `/members`.
+   - Use letters, numbers, and hyphens.
+   - Do not reuse a slug already assigned to another page.
+6. Select a **Status**:
+   - `Draft`: not normally visible to public visitors.
+   - `Pending Review`: not normally visible to public visitors.
+   - `Published`: visible when its publish date has arrived.
+   - `Archived`: not normally visible to public visitors.
+7. Select the **Minimum Access Role**.
+8. Select a **Theme / Template**.
+9. Enter the page content in the editor.
+10. Click **Save Page**.
+
+### Give a dynamic page access permissions
+
+Use the **Minimum Access Role** field:
+
+- `Unregistered`: anyone can view it.
+- `Registered`: only logged-in registered users and higher roles.
+- `Editor`: Editors, Managers, and Administrators.
+- `Manager`: Managers and Administrators.
+- `Administrator`: Administrators only.
+
+The page must also be `Published`, and its `publish_at` date must not be in
+the future. Editors and higher roles can see unpublished pages because they are
+treated as staff by the current public route.
+
+### Edit, archive, or delete a dynamic page
+
+From **Pages**:
+
+- Click **Edit** to change the title, slug, content, template, status, or role.
+- Deleting a page first moves it to the trash by setting its status to
+  `Deleted`.
+- Use **Restore** to return a deleted page to `Draft`.
+- Permanent deletion is available only to Administrators and cannot be undone.
+
+## 4. Create a static page
+
+A static page is an EJS file in `views/pages/`. It is useful when the page
+needs custom HTML or custom server-rendered logic rather than ordinary CMS
+content.
+
+Create a file such as:
+
+```text
+views/pages/contact.ejs
+```
+
+Example:
+
+```ejs
+<%# theme: landing %>
+<%# minRole: Registered %>
+<h1>Contact Us</h1>
+<p>This page is rendered from views/pages/contact.ejs.</p>
+<p>Email: support@example.com</p>
+```
+
+The optional first-line EJS comment selects the theme for this static page:
+
+```ejs
+<%# theme: landing %>
+```
+
+Use the theme directory name under `views/themes/`. The `theme` directive
+overrides the database page's template, if a page with the same slug exists.
+`layout` can be used as an equivalent directive for compatibility with
+layout-oriented terminology. If the selected theme is not found, the default
+theme is used.
+
+Static pages can also require a minimum user role:
+
+```ejs
+<%# minRole: Registered %>
+```
+
+Supported roles are `Unregistered`, `Registered`, `Editor`, `Manager`, and
+`Administrator`. If `minRole` is omitted, the page defaults to
+`Unregistered`. Unauthenticated visitors are sent to the login page, while
+authenticated users without sufficient privileges receive a forbidden response.
+
+After restarting the application, visit:
+
+```text
+http://localhost:3000/contact
+```
+
+The public router checks `views/pages/<slug>.ejs` before checking the database.
+Therefore, `views/pages/contact.ejs` takes priority over a database page whose
+slug is `contact`.
+
+### Important: static-page permissions
+
+Static page access is controlled by the optional `minRole` directive in the
+file. Checking `user` in the EJS file only hides HTML; it does not reliably
+protect the URL or data.
+
+For a protected page, use a dynamic page and set its minimum role, or add a
+dedicated Express route with role middleware in the application source. The
+reusable role middleware is in `src/middleware/auth.ts`.
+
+## 5. Create a theme/template
+
+In the current CMS, a selectable template is an EJS file named `index.ejs`
+inside a directory under `views/themes/`.
+
+Create this structure:
+
+```text
+views/
+  themes/
+    marketing/
+      index.ejs
+      assets/
+        css/
+          style.css
+```
+
+Example `views/themes/marketing/index.ejs`:
+
+```ejs
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><%= title %></title>
+    <link rel="stylesheet" href="/themes/<%= currentTheme %>/assets/css/style.css">
+</head>
+<body>
+    <header>
+        <a href="/"><%= siteName || 'Radix' %></a>
+    </header>
+
+    <main>
+        <h1><%= title %></h1>
+        <%- content %>
+    </main>
+</body>
+</html>
+```
+
+Example `views/themes/marketing/assets/css/style.css`:
+
+```css
+body {
+    max-width: 900px;
+    margin: 0 auto;
+    font-family: sans-serif;
+}
+```
+
+### Apply the template to a page
+
+1. Restart the application if necessary.
+2. Open **Admin > Themes** to confirm that `marketing` was discovered.
+3. Create or edit a dynamic page.
+4. Select `Marketing` in **Theme / Template**.
+5. Save the page.
+6. Visit the page URL.
+
+The theme scanner discovers directories under `views/themes/`. The public
+renderer then loads `views/themes/<template_name>/index.ejs`.
+
+### Template variables
+
+Dynamic themes currently receive values including:
+
+```text
+title          Page title
+content        Saved HTML content
+page            Complete database page object
+user            Logged-in user, or undefined
+currentTheme   Selected template name
+siteName       APP_NAME from environment
+appVersion     Current application version
+```
+
+Use `<%= value %>` for escaped text. Use `<%- content %>` only for trusted HTML
+that should be rendered as markup. The current CMS stores rich-text HTML and
+the default theme renders it unescaped.
+
+## 6. Create and manage users
+
+Only an Administrator can manage users.
+
+1. Open **Admin > Users & Roles**.
+2. Complete **Create New User**:
+   - **Username**: required and unique.
+   - **Full Name**: optional.
+   - **Email**: optional, but must be unique when supplied.
+   - **Password**: required.
+   - **Role**: choose the user's highest allowed role.
+3. Click **Add User**.
+
+Passwords are stored as bcrypt hashes, not as plain text.
+
+### Edit a user
+
+Click **Edit** beside a user to change:
+
+- Full name
+- Username
+- Email
+- Role
+- Password
+
+Leave **New Password** blank to keep the current password. Changing your own
+role updates the current session's role as well.
+
+### Delete a user
+
+Click **Delete** beside the account. The currently logged-in administrator
+cannot delete their own active account.
+
+## 7. Media uploads
+
+Editors and Administrators can open **Admin > Media Library**.
+
+1. Choose an image file.
+2. Upload it.
+3. Use its `/uploads/<filename>` URL in page content or settings.
+
+The current upload limit is 10 MB. Supported image types are JPG, PNG, GIF,
+WEBP, and SVG. Administrators can delete media files.
+
+## 8. Site settings
+
+Administrators can open **Admin > Settings** to configure:
+
+- Site logo path or URL
+- SMTP host, port, encryption, username, and password
+- Sender email address
+- Test email delivery
+
+Settings are stored in the database. Database connection details and secrets
+remain in `.env`.
+
+## 9. Troubleshooting
+
+### My page shows the wrong content
+
+Check whether `views/pages/<slug>.ejs` exists. A static file overrides the
+database page with the same slug.
+
+### My new template is not listed
+
+Confirm the file is exactly:
+
+```text
+views/themes/<name>/index.ejs
+```
+
+Then restart the application and refresh the admin page.
+
+### My page is not visible publicly
+
+For a dynamic page, check:
+
+1. Status is `Published`.
+2. `publish_at` is not in the future.
+3. The visitor's role meets **Minimum Access Role**.
+4. No static override is interfering.
+
+### Source changes do not appear
+
+Use `npm run dev` during development. For production-style execution, rebuild
+before starting:
+
+```powershell
+npm run build
+npm run app
+```
+
+The `dist/` folder is generated output and should not be edited directly.