radix-cms 0.1.0 → 1.0.0

package/.env.example

@@ -0,0 +1,17 @@
+APP_NAME=Radix
+APP_VERSION=1.0.0
+SITE_URL=localhost
+SITE_PORT=3000
+DB_HOST=
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+MAIL_HOST=
+MAIL_PORT=
+MAIL_SECURE=
+MAIL_USER=
+MAIL_PASS=
+THEME=default
+SESSION_SECRET=
+STATUS=live
+TINYMCEAPI=

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to Radix CMS are documented here.
+
+## [1.0.0] - 2026-09-07
+
+### Added
+
+- Initial public release of Radix CMS.
+- GNU GPL v3.0-or-later licensing and source-file SPDX identifiers.

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to Radix CMS
+
+Thank you for your interest in contributing to Radix CMS.
+
+## Before contributing
+
+- Review the [README](README.md) for setup and project requirements.
+- Review the [GNU GPL v3.0-or-later license](LICENSE).
+- Do not include credentials, API keys, uploaded files, or other private data in
+  issues, pull requests, or commits.
+
+## Development
+
+Install dependencies and run the development server:
+
+```powershell
+npm install
+npm run dev
+```
+
+Before submitting a change, build the project and confirm that it completes
+successfully:
+
+```powershell
+npm run build
+```
+
+## Reporting issues
+
+For support requests, please use [the support request form](https://ultraspark.net/request-support/)
+or email [support@ultraspark.net](mailto:support@ultraspark.net).
+
+When reporting a bug, include the Radix CMS version, Node.js version, database
+engine/version, reproduction steps, and relevant logs. Remove secrets before
+sharing logs.
+
+## Pull requests
+
+Describe the problem and solution, keep changes focused, and mention the
+validation you performed.

package/LICENSE

@@ -0,0 +1,197 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+2. Basic Freedoms.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated in this License.  Sublicensing is not allowed;
+section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any law fulfilling obligations under article 11 of the
+WIPO copyright treaty adopted on 20 December 1996, or similar laws
+prohibiting or restricting circumvention of such measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and

package/NOTICE

@@ -0,0 +1,3 @@
+RadixCMS
+Copyright (C) 2026 Ultra Spark Software
+This project is open-source software licensed under the GNU General Public License v3.0.

package/README.md

@@ -1,108 +1,178 @@
-\# Radix CMS
+# Radix CMS
 
+Radix CMS is a Node.js and TypeScript content management system for building
+custom websites and web applications. It provides a public site, an
+administration panel, database-backed pages, users and roles, media uploads,
+themes, and site settings.
 
+## Features
 
-Basic CMS for building custom web applications.
+- Public pages rendered with Express and EJS
+- Admin dashboard at `/admin`
+- MySQL/MariaDB database storage
+- Page drafts, publishing, archiving, and access roles
+- User roles: Registered, Editor, Manager, and Administrator
+- Media uploads
+- EJS themes and static pages
+- Email and site settings
+- Update checking from the admin panel
 
+## Requirements
 
+- Node.js 18 or newer
+- npm
+- MySQL 8+ or MariaDB
 
-\## Status: Under Active Development 🚧
-
-
-
-\*\*Please Note:\*\* This version (`v0.1.0`) is an initial development release and acts as a placeholder to reserve the namespace. A fully working, feature-rich version of the CMS will be uploaded soon. 
-
-
-
-\---
-
-
-
-\## Installation
+## Installation
 
+Clone or download the project, then install its dependencies:
 
+```powershell
+npm install
+```
 
-Once published, you can install the package via npm:
+Create a local environment file from the example:
 
+```powershell
+Copy-Item .env.example .env
+```
 
+On macOS or Linux:
 
 ```bash
-
-npm install radix-cms
-
+cp .env.example .env
 ```
 
-\*(Note: Replace `radix-cms` with your final unique or scoped package name if it changes).\*
-
-
-
-\---
+Edit `.env` with your database credentials and a strong session secret. Do not
+commit `.env` or share it publicly.
 
+Start the development server:
 
+```bash
+npm run dev
+```
 
-\## Usage (v0.1.0 Placeholder)
-
-
-
-The current version exports a basic HTTP server function to verify your initialization. You can import and launch the server within your project.
-
-
-
-\### Example
-
-
-
-Create an `app.js` file in your project and add the following code:
-
-
+Open the public site at <http://localhost:3000/> and the administration panel
+at <http://localhost:3000/admin>.
 
-```javascript
+## First-time setup
 
-const { startCMS } = require('radix-cms');
+If the database settings are incomplete or the database is unavailable, Radix
+redirects to <http://localhost:3000/admin/install>.
 
+The installer:
 
+1. Tests the MySQL/MariaDB connection.
+2. Saves the database settings to `.env`.
+3. Creates the database schema and default content.
+4. Creates the first Administrator account.
+5. Redirects to the admin login page.
 
-// Start the CMS server with optional custom configuration
+Use the credentials created during setup to sign in at `/admin/login`.
 
-startCMS({
+## Configuration
 
-&#x20; hostname: '127.0.0.1',
+The main environment variables are:
 
-&#x20; port: 3000
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `APP_NAME` | Application name shown by the site | `Radix` |
+| `APP_VERSION` | Application version | `0.12.0` |
+| `SITE_URL` | Site URL used by the application | `localhost` |
+| `SITE_PORT` | HTTP port | `3000` |
+| `DB_HOST` | MySQL/MariaDB host | `127.0.0.1` |
+| `DB_PORT` | MySQL/MariaDB port | `3306` |
+| `DB_USER` | Database user | - |
+| `DB_PASSWORD` | Database password | - |
+| `DB_NAME` | Database name | `radix` |
+| `SESSION_SECRET` | Secret used to sign sessions | — |
+| `THEME` | Active theme name | `default` |
+| `STATUS` | Site status setting | `live` |
+| `MAIL_HOST` | SMTP server host | - |
+| `MAIL_PORT` | SMTP server port | - |
+| `MAIL_SECURE` | Whether SMTP uses TLS | - |
+| `MAIL_USER` | SMTP username | - |
+| `MAIL_PASS` | SMTP password | - |
+| `TINYMCEAPI` | Optional TinyMCE API key | - |
 
-});
+The admin settings screen can also manage application settings after the
+initial installation.
 
-```
+## npm scripts
 
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Run the TypeScript application with file watching |
+| `npm run build` | Compile TypeScript into `dist/` and copy the SQL schema |
+| `npm start` | Build the application and start the compiled server |
+| `npm run app` | Start the already-compiled server |
 
+For a production deployment, build once with `npm run build`, set production
+environment variables, and run the compiled application with `npm run app`.
 
-\### Configuration Options
+## Customization
 
+### Themes
 
+Public themes are stored in `views/themes/`. A theme can contain an EJS
+template and assets such as CSS and JavaScript. Theme assets are available
+under `/themes/<theme-name>/`.
 
-You can pass an optional configuration object to `startCMS()`:
+### Static pages
 
+Static EJS pages can be added to `views/pages/`. For example,
+`views/pages/contact.ejs` can provide a custom `/contact` page.
 
+### Dynamic pages
 
-| Property | Type | Default | Description |
+Editors and Administrators can create database-backed pages from the **Pages**
+screen. Each page has a title, slug, status, access role, template, and
+editable content.
 
-| :--- | :--- | :--- | :--- |
+More detailed user and developer documentation is available in:
 
-| `hostname` | `string` | `'127.0.0.1'` | The IP address or hostname the server binds to. |
+- [`docs/CMS_USER_GUIDE.md`](docs/CMS_USER_GUIDE.md)
+- [`docs/CMS_CODE_GUIDE.md`](docs/CMS_CODE_GUIDE.md)
 
-| `port` | `number` | `3000` | The port network traffic will use. |
+## Production and security notes
 
+- Use a long, random `SESSION_SECRET`.
+- Never commit `.env`, database passwords, SMTP credentials, or API keys.
+- Run behind HTTPS in production.
+- Use a dedicated database user with only the permissions Radix requires.
+- Back up the database and uploaded media regularly.
+- Review uploaded files and server permissions before exposing the application
+  to the public internet.
+- The default Express session store is intended for development. Use a
+  production-ready session store for multi-instance or high-traffic
+  deployments.
 
+## Troubleshooting
 
-\---
+### The application redirects to `/admin/install`
 
+Check that `DB_HOST`, `DB_USER`, `DB_PASSWORD`, and `DB_NAME` are present in
+`.env`, and verify that MySQL/MariaDB is running and reachable.
 
+### The server starts but pages or templates are missing
 
-\## License
+Run:
 
+```bash
+npm run build
+```
 
+The compiled application expects the `views/`, `public/`, and generated
+`dist/sql/radix.sql` files to be available.
 
-This project is licensed under the MIT License.
+## Contributing
 
+Bug reports and feature requests are welcome through the project's GitHub
+Issues page. Please include the Radix version, Node.js version, database
+engine/version, reproduction steps, and relevant logs. Never include secrets
+from `.env` in an issue.
 
+## License
 
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
+Copyright © 2026 Ultra Spark Software

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are intended for the latest supported Radix CMS release. Users
+should keep their installation and dependencies up to date.
+
+## Reporting a vulnerability
+
+Please do not report security vulnerabilities in public issues or pull
+requests. Use either of these private support methods:
+
+- [Private support request form](https://ultraspark.net/request-support/)
+- [support@ultraspark.net](mailto:support@ultraspark.net)
+
+Include a description of the vulnerability, affected version, reproduction
+steps or proof of concept, and any suggested mitigation. Do not include
+production credentials or other sensitive data unless it is necessary for
+investigation.
+
+We will acknowledge the report, investigate it, and coordinate disclosure and
+fix details with the reporter.

package/dist/app.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+"use strict";
+/**************************************************************************************************
+* RadixCMS
+*
+* DESCRIPTION: application startup, middleware, and route configuration.
+*
+* Copyright (C) 2026 Ultra Spark Software <salve@ultraspark.net>
+* SPDX-License-Identifier: GPL-3.0-or-later
+**************************************************************************************************/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const express_session_1 = __importDefault(require("express-session"));
+const path_1 = __importDefault(require("path"));
+// Import Routers
+const admin_1 = __importDefault(require("./routes/admin"));
+const index_1 = __importDefault(require("./routes/index"));
+const dbInit2_1 = require("./init/dbInit2");
+``;
+const app = (0, express_1.default)();
+const PORT = process.env.SITE_PORT || 3000;
+let app_name = process.env.APP_NAME || 'Radix';
+let app_version = process.env.APP_VERSION || '0.10.0';
+// ==========================================
+// 1. VIEW ENGINE CONFIGURATION (EJS)
+// ==========================================
+app.set('view engine', 'ejs');
+app.set('views', path_1.default.join(__dirname, '../views'));
+// ==========================================
+// 2. PARSING & SESSION MIDDLEWARE
+// ==========================================
+app.use(express_1.default.json());
+app.use(express_1.default.urlencoded({ extended: true }));
+app.use((0, express_session_1.default)({
+    secret: process.env.SESSION_SECRET || 'radix-secret-key-change-this-in-production',
+    resave: false,
+    saveUninitialized: false,
+    cookie: {
+        maxAge: 1000 * 60 * 60 * 24 // 24 Hours
+    }
+}));
+// ==========================================
+// 3. STATIC FILE SERVING
+// ==========================================
+// Serve public assets (CSS, JS, fonts)
+app.use(express_1.default.static(path_1.default.join(__dirname, '../public')));
+// Serve theme assets such as /themes/default/assets/css/style.css
+app.use('/themes', express_1.default.static(path_1.default.join(__dirname, '../views/themes')));
+// Serve media library uploads dynamically
+app.use('/uploads', express_1.default.static(path_1.default.join(__dirname, '../public/uploads')));
+// ==========================================
+// 4. ROUTE MOUNTING
+// ==========================================
+// CRITICAL: /admin MUST be mounted before / so that /:slug does not catch /admin URLs
+app.use('/admin', admin_1.default);
+app.use('/', index_1.default);
+// ==========================================
+// 5. SERVER INITIALIZATION
+// ==========================================
+async function startServer() {
+    try {
+        await (0, dbInit2_1.initDatabase)();
+    }
+    catch (err) {
+        console.error('Error during DB initialization:', err);
+    }
+    app.listen(PORT, () => {
+        console.log(`\n==================================================`);
+        console.log(` 🚀 ${app_name} ${app_version} is running!`);
+        console.log(` 🌐 Public Site:  http://localhost:${PORT}`);
+        console.log(` 🔑 Admin Panel:  http://localhost:${PORT}/admin`);
+        console.log(`==================================================\n`);
+        console.log('Start Time:', new Date().toLocaleString(), '\n');
+    });
+}
+startServer();
+exports.default = app;

package/dist/config/db.js

@@ -0,0 +1,66 @@
+"use strict";
+/**************************************************************************************************
+* RadixCMS
+*
+* DESCRIPTION: database connection pool and query helpers.
+*
+* Copyright (C) 2026 Ultra Spark Software <salve@ultraspark.net>
+* SPDX-License-Identifier: GPL-3.0-or-later
+**************************************************************************************************/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promise_1 = __importDefault(require("mysql2/promise"));
+const dotenv_1 = __importDefault(require("dotenv"));
+// Load env now; installer may re-load dotenv later when writing .env
+dotenv_1.default.config();
+let pool = null;
+let lastConfigKey = '';
+function makeConfigKey() {
+    return `${process.env.DB_HOST || ''}:${process.env.DB_PORT || ''}|${process.env.DB_USER || ''}|${process.env.DB_NAME || ''}`;
+}
+async function ensurePool() {
+    const key = makeConfigKey();
+    if (pool && key === lastConfigKey)
+        return pool;
+    // close existing pool if config changed
+    if (pool) {
+        try {
+            await pool.end();
+        }
+        catch (e) { /* ignore */ }
+        pool = null;
+    }
+    console.log(`[DB Pool] Creating pool for ${process.env.DB_HOST || '127.0.0.1'}:${process.env.DB_PORT || 3306} (user=${process.env.DB_USER || 'unknown'})`);
+    pool = promise_1.default.createPool({
+        host: process.env.DB_HOST || '127.0.0.1',
+        user: process.env.DB_USER,
+        password: process.env.DB_PASSWORD,
+        database: process.env.DB_NAME,
+        port: Number(process.env.DB_PORT) || 3306,
+        waitForConnections: true,
+        connectionLimit: 10,
+        queueLimit: 0,
+        connectTimeout: 5000
+    });
+    lastConfigKey = key;
+    return pool;
+}
+exports.default = {
+    async execute(sql, params) {
+        const p = await ensurePool();
+        // mysql2's execute has its own stricter generic constraints; cast the result to preserve caller generics
+        const res = await p.execute(sql, params);
+        return res;
+    },
+    async query(sql, params) {
+        const p = await ensurePool();
+        const res = await p.query(sql, params);
+        return res;
+    },
+    async getConnection() {
+        const p = await ensurePool();
+        return p.getConnection();
+    }
+};