@reldens/cms 0.47.0 → 0.49.0

package/.claude/templating-system-guide.md

@@ -0,0 +1,349 @@
+# Enhanced Templating System Guide
+
+## System Variables
+
+Every template has access to system variables providing context about the current request:
+
+```html
+{{currentRequest.baseUrl}}
+{{currentRequest.protocol}}
+{{currentRequest.host}}
+{{currentRequest.path}}
+{{currentRequest.method}}
+{{currentRequest.userAgent}}
+{{currentRequest.isSecure}}
+
+{{currentRoute.id}}
+{{currentRoute.path}}
+{{currentRoute.title}}
+{{currentRoute.template}}
+{{currentRoute.layout}}
+
+{{currentDomain.current}}
+{{currentDomain.default}}
+{{currentDomain.resolved}}
+
+{{systemInfo.environment}}
+{{systemInfo.nodeVersion}}
+{{systemInfo.timestamp}}
+```
+
+## Template Functions
+
+### URL Transformers
+
+The CMS provides three URL transformers with different behaviors for CDN support:
+
+#### [url()] - Public URL (No CDN)
+
+Generates URLs using the **public base URL** without CDN support.
+
+```html
+[url(/articles)]
+[url(/contact#form)]
+[url(/css/styles.css)]
+```
+
+**Output:**
+- Without CDN: `https://example.com/css/styles.css`
+- With CDN configured: `https://example.com/css/styles.css` (same, CDN ignored)
+
+**Use for:** Internal application routes, API endpoints, form actions.
+
+#### [cdn()] - CDN or Public URL
+
+Generates URLs using the **CDN URL if configured**, otherwise falls back to public URL.
+
+```html
+[cdn(/css/styles.css)]
+[cdn(/js/scripts.js)]
+[cdn(/assets/web/logo.png)]
+```
+
+**Output:**
+- Without CDN: `https://example.com/css/styles.css`
+- With CDN configured: `https://cdn.example.com/css/styles.css`
+
+**Use for:** Static assets outside `/assets` folder (CSS, JS, fonts, etc.).
+
+#### [asset()] - CDN or Public URL + /assets Prefix
+
+Generates URLs using the **CDN URL if configured** and **automatically prepends `/assets`** to the path.
+
+```html
+[asset(/web/logo.png)]
+[asset(/images/hero.jpg)]
+```
+
+**Output:**
+- Without CDN: `https://example.com/assets/web/logo.png`
+- With CDN configured: `https://cdn.example.com/assets/web/logo.png`
+
+**Use for:** Static assets inside `/assets` folder (images, downloads, media files).
+
+---
+
+### URL Transformer Best Practices
+
+**Based on folder structure:**
+
+```
+public/
+  assets/          # Use [asset(/file)] OR [cdn(/assets/file)]
+    web/
+    images/
+    downloads/
+  css/             # Use [cdn(/css/file)]
+  js/              # Use [cdn(/js/file)]
+  fonts/           # Use [cdn(/fonts/file)]
+```
+
+**Examples:**
+
+```html
+<!-- Files in public/assets/ -->
+<meta property="og:image" content="[asset(/web/logo.png)]"/>
+<img src="[asset(/images/hero.jpg)]" alt="Hero"/>
+
+<!-- Files in public/css/, public/js/, etc. -->
+<link rel="stylesheet" href="[cdn(/css/styles.css)]"/>
+<script src="[cdn(/js/scripts.js)]"></script>
+
+<!-- Internal routes -->
+<form action="[url(/api/submit)]" method="post">
+<a href="[url(/articles)]">Articles</a>
+```
+
+**Key Rules:**
+- `[asset(/file)]` adds `/assets` prefix automatically → Use for files in `/assets` folder
+- `[cdn(/assets/file)]` requires full path → Alternative for files in `/assets` folder
+- `[cdn(/css/file)]` requires full path → Use for files outside `/assets` (css, js, fonts)
+- `[url(/path)]` never uses CDN → Use for application routes only
+
+**Recommendation:** Use `[asset()]` for `/assets` files (cleaner syntax), `[cdn()]` for everything else.
+
+### Date Formatting
+
+```html
+[date()]
+[date(now, Y-m-d)]
+[date(2024-01-01, d/m/Y)]
+```
+
+### Internationalization
+
+```html
+[translate(welcome.message)]
+[t(hello.world, Hello World!)]
+[t(greeting, Hi {name}!, {name: John})]
+```
+
+## Enhanced Context Passing
+
+Child content blocks and partials receive context from parent pages:
+
+```html
+<entity name="cmsBlocks" field="name" value="article-sidebar"/>
+
+{{currentEntity.title}}
+{{currentEntity.id}}
+{{currentEntity.template}}
+```
+
+## Entity Rendering
+
+### Single Entity
+
+```html
+<entity name="cmsBlocks" field="name" value="header-main"/>
+<entity name="cmsBlocks" field="name" value="sidebar-left"/>
+<entity name="articles" id="123"/>
+<entity name="cmsPages" id="1"/>
+```
+
+### Single Field Collections
+
+Extract and concatenate a single field from multiple records:
+
+```html
+<collection name="cmsBlocks" filters="{status: 'active', category: 'navigation'}" field="content"/>
+<collection name="articles" filters="{featured: true}" field="title"/>
+<collection name="articles" filters="{featured: true}" field="title" data="{limit: 5, sortBy: 'created_at', sortDirection: 'desc'}"/>
+```
+
+### Loop Collections
+
+```html
+<collection name="cmsBlocks" filters="{status: 'active'}">
+    <div class="block">
+        <h3>{{row.title}}</h3>
+        <div class="content">{{row.content}}</div>
+    </div>
+</collection>
+
+<collection name="articles" filters="{category: 'technology'}">
+    <div class="article">
+        <h4>{{row.title}}</h4>
+        <p>{{row.summary}}</p>
+        <img src="{{row.featured_image}}" alt="{{row.title}}">
+    </div>
+</collection>
+```
+
+### Paginated Collections
+
+```html
+<collection name="articles"
+    filters="{featured: true}"
+    data="{limit: 10, sortBy: 'created_at', sortDirection: 'desc'}"
+    pagination="articles-1"
+    container="pagedCollection"
+    prevPages="2"
+    nextPages="2">
+    <div class="article-card">
+        <h4>{{row.title}}</h4>
+        <p>{{row.summary}}</p>
+        <span class="date">{{row.created_at}}</span>
+    </div>
+</collection>
+```
+
+**Pagination Attributes:**
+
+- `pagination="collection-id"` - Enables pagination with unique identifier
+- `container="templateName"` - Custom pagination template (defaults to "pagedCollection")
+- `prevPages="2"` - Number of previous page links to show (default: 2)
+- `nextPages="2"` - Number of next page links to show (default: 2)
+
+**Pagination URL Parameters:**
+
+```
+/articles?articles-1-key={"page":2,"limit":10,"sortBy":"created_at","sortDirection":"desc"}
+```
+
+**Available Pagination Template Variables:**
+
+- `{{&collectionContentForCurrentPage}}` - Rendered collection items for current page
+- `{{currentPage}}` - Current page number
+- `{{totalPages}}` - Total number of pages
+- `{{totalRecords}}` - Total number of records
+- `{{prevPageUrl}}` / `{{nextPageUrl}}` - Previous/next page URLs
+- `{{&prevPageLabel}}` / `{{&nextPageLabel}}` - Previous/next link labels
+- `{{#prevPages}}` / `{{#nextPages}}` - Arrays of page objects with pageUrl and pageLabel
+- `{{hasNextPage}}` / `{{hasPrevPage}}` - Boolean flags for navigation availability
+
+## Custom Partials
+
+### HTML-style Syntax
+
+```html
+<partial name="hero"
+    sectionStyle=" bg-black"
+    bigTextHtml="A free open-source platform!"
+    mediumTextHtml="Build with Node.js, MySQL"
+    imageUrl="/assets/web/logo.png"
+    imageAlt="Logo" />
+
+<partial name="productCard"
+    title="Premium Package"
+    price="$99"
+    highlighted="true">
+</partial>
+```
+
+### Mustache Syntax
+
+```html
+{{>hero -{
+    bigTextHtml: "Welcome!",
+    mediumTextHtml: "Build with Node.js",
+    imageUrl: "https://example.com/hero.jpg",
+    ctaText: "Get Started",
+    ctaLink: "/documentation"
+}-}}
+
+<collection name="cmsPages" filters="{featured: true}" data="{limit: 3}">
+    {{>cardView -{row}-}}
+</collection>
+
+{{>productCard -{
+    title: "Premium Package",
+    price: "$99",
+    features: ["Advanced Analytics", "Priority Support"],
+    highlighted: true
+}-}}
+```
+
+## Collection Query Options
+
+Collections support advanced query parameters:
+
+- **limit** - Maximum number of records to return
+- **offset** - Number of records to skip (for pagination)
+- **sortBy** - Field name to sort by
+- **sortDirection** - Sort direction ('asc' or 'desc')
+
+### Examples
+
+```html
+<collection name="articles" filters="{}" field="title" data="{limit: 5, sortBy: 'title'}"/>
+
+<collection name="articles" filters="{published: true}" data="{limit: 10, offset: 20, sortBy: 'created_at', sortDirection: 'desc'}">
+  <article>{{row.title}}</article>
+</collection>
+
+<collection name="articles" filters="{featured: true}" data="{limit: 3, sortBy: 'created_at', sortDirection: 'desc'}">
+  <div class="featured-article">{{row.title}}</div>
+</collection>
+```
+
+## Layout System
+
+### page.html - Full HTML wrapper
+
+```html
+<!DOCTYPE html>
+<html lang="{{locale}}">
+<head>
+    <title>{{title}}</title>
+    <meta name="description" content="{{description}}"/>
+    <link href="[url(/css/styles.css)]" rel="stylesheet"/>
+</head>
+<body class="{{siteHandle}}">
+    {{&content}}
+    <script src="[url(/js/scripts.js)]"></script>
+</body>
+</html>
+```
+
+### layouts/default.html - Body content only
+
+```html
+<entity name="cmsBlocks" field="name" value="header-main"/>
+
+<main id="main" class="main-container">
+    <div class="container">
+        <div class="row">
+            <div class="col-md-3">
+                <entity name="cmsBlocks" field="name" value="sidebar-left"/>
+            </div>
+            <div class="col-md-9">
+                {{&content}}
+            </div>
+        </div>
+    </div>
+</main>
+
+<entity name="cmsBlocks" field="name" value="footer-main"/>
+```
+
+## Content Blocks
+
+Create reusable content blocks in the cms_blocks table via admin panel:
+
+```sql
+INSERT INTO cms_blocks (name, title, content) VALUES
+('contact-info', 'Contact Information', '<p>Email: info@example.com</p>'),
+('article-sidebar', 'Article Categories',
+'<div class="categories"><h3>Categories</h3><ul><li><a href="[url(/articles/technology)]">Technology</a></li></ul></div>');
+```

package/CLAUDE.md

@@ -14,6 +14,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - Template reloading for development
 - Caching system for performance
 - Event-driven architecture for extensibility
+- Password encryption and management - Automatic password encryption with PBKDF2
 
 ## Key Commands
 
@@ -24,10 +25,61 @@ npx reldens-cms
 # Generate entities from database
 npx reldens-cms-generate-entities
 
+# Update user password via CLI
+npx reldens-cms-update-password --email=admin@example.com
+
 # Or via npm scripts
 npm run generate-entities
 ```
 
+## Password Management
+
+### CLI Password Update Command
+
+The CMS provides a dedicated CLI command for securely updating user passwords:
+
+```bash
+# Interactive mode (recommended - will prompt for password)
+npx reldens-cms-update-password --email=admin@example.com
+
+# By username
+npx reldens-cms-update-password --username=admin
+
+# With password in command (less secure)
+npx reldens-cms-update-password --email=admin@example.com --password=newPassword123
+```
+
+**Options**:
+- `--email=[email]` - User email address
+- `--username=[username]` - User username
+- `--password=[password]` - New password (prompted if not provided)
+- `--help` or `-h` - Show this help message
+
+**Notes**:
+- Works with any storage driver (prisma, objection-js, mikro-orm)
+- Uses `RELDENS_STORAGE_DRIVER` environment variable to detect the driver
+- Automatically loads entities and Prisma client (if using Prisma)
+
+### Automatic Password Encryption
+
+The CMS automatically encrypts passwords when saving user records through the admin panel using the `PasswordEncryptionHandler`:
+
+- Listens to `reldens.adminBeforeEntitySave` event
+- Detects password field changes in users entity
+- Encrypts passwords using PBKDF2 (100k iterations, SHA-512)
+- Stores passwords in `salt:hash` format
+- **Enabled by default** - can be disabled with `enablePasswordEncryption: false` in Manager config
+
+**Password Encryption Algorithm**:
+- **Method**: PBKDF2 (Password-Based Key Derivation Function 2)
+- **Iterations**: 100,000
+- **Key Length**: 64 bytes
+- **Digest**: SHA-512
+- **Salt Length**: 32 bytes (randomly generated)
+- **Storage Format**: `salt:hash` (192 characters total)
+
+See `.claude/password-management-guide.md` for comprehensive password management documentation.
+
 ## Architecture Overview
 
 The CMS follows a modular architecture with specialized classes following SOLID principles:
@@ -39,6 +91,7 @@ The CMS follows a modular architecture with specialized classes following SOLID
 - Handles configuration and environment variables
 - Manages multi-domain setup and security
 - Coordinates service lifecycle
+- Initializes password encryption handler
 
 **lib/frontend.js** - Frontend orchestrator
 - Coordinates all frontend operations
@@ -52,6 +105,18 @@ The CMS follows a modular architecture with specialized classes following SOLID
 - Processes file uploads
 - Builds admin UI from entity configurations
 
+**lib/password-encryption-handler.js** - Password encryption handler
+- Automatic password encryption for users entity
+- Event-driven architecture
+- PBKDF2 encryption with 100k iterations
+- Detects and skips already-encrypted passwords
+- Configurable entity and field names
+
+**lib/admin-manager/router-contents.js** - Admin routing and form handling
+- Password field handling (type="password", empty on edit)
+- Password updates optional (skip if empty when editing)
+- Configurable password field names via `passwordFieldNames`
+
 ### Installation & Setup
 
 **lib/installer.js** - Installation orchestrator
@@ -252,7 +317,7 @@ The CMS uses these core tables:
 - **cms_pages_meta** - Page-specific metadata
 
 ### User Management (Optional)
-- **users** - User authentication
+- **users** - User authentication (with encrypted passwords)
 - **roles** - Role definitions
 
 ## Template System
@@ -342,13 +407,21 @@ templates/
 
 **Template Functions:**
 ```html
-[url(/articles)]                    <!-- URL generation -->
-[asset(/img/logo.png)]              <!-- Asset URLs -->
+[url(/articles)]                    <!-- URL generation (no CDN) -->
+[cdn(/css/styles.css)]              <!-- CDN URL (or public URL if no CDN) -->
+[asset(/web/logo.png)]              <!-- Asset URL with /assets prefix (uses CDN if available) -->
 [date(now, Y-m-d)]                  <!-- Date formatting -->
 [translate(welcome.message)]        <!-- i18n -->
 [t(key, Default, {var: value})]     <!-- i18n with interpolation -->
 ```
 
+**URL Transformer Selection:**
+- `[url()]` - Application routes (never uses CDN)
+- `[cdn()]` - Static assets outside `/assets` (CSS, JS, fonts)
+- `[asset()]` - Static assets inside `/assets` folder (images, media)
+
+See `.claude/templating-system-guide.md` for detailed URL transformer documentation.
+
 ## Configuration
 
 ### Environment Variables (.env)
@@ -399,6 +472,9 @@ const cms = new Manager({
     },
     adminRoleId: 99,
 
+    // Password encryption (enabled by default)
+    enablePasswordEncryption: true,  // Set to false to disable
+
     // Performance
     cache: true,
     reloadTime: -1,  // Development: reload on every request
@@ -444,6 +520,7 @@ The CMS provides extensive event hooks for customization:
 - `reldens.setupAdminRouter` - Setup admin routes
 - `reldens.setupAdminRoutes` - After route setup
 - `reldens.setupAdminManagers` - After manager setup
+- `reldens.adminBeforeEntitySave` - Before entity save (used by password encryption handler)
 
 ### Template Reloading Events
 - `reldens.templateReloader.templatesChanged` - Templates changed
@@ -495,6 +572,8 @@ Define custom entity configurations in `entitiesConfig`:
 ## Security Features
 
 - **Authentication** - Role-based admin access
+- **Password Encryption** - PBKDF2 with 100k iterations, SHA-512
+- **Automatic Password Encryption** - Event-driven encryption on save (enabled by default)
 - **CSRF Protection** - Via session tokens
 - **File Upload Validation** - MIME type and extension checking
 - **Entity Access Control** - Public/private entity rules
@@ -518,6 +597,8 @@ Define custom entity configurations in `entitiesConfig`:
 8. **Event hooks are async** - use await when emitting events
 9. **Template reloading is development-only** - disable in production
 10. **Multi-domain requires proper configuration** - set up domain mapping correctly
+11. **Password encryption is automatic** - enabled by default for users entity
+12. **Never store plain text passwords** - always use Encryptor.encryptPassword()
 
 ## Common File Paths
 
@@ -528,6 +609,8 @@ Define custom entity configurations in `entitiesConfig`:
 - **Public assets:** `public/`
 - **Environment:** `.env`
 - **Install lock:** `install.lock`
+- **Password CLI:** `bin/reldens-cms-update-password.js`
+- **Password handler:** `lib/password-encryption-handler.js`
 
 ## Troubleshooting
 
@@ -551,6 +634,12 @@ Define custom entity configurations in `entitiesConfig`:
 - Check entity access configuration
 - Verify relationship mappings
 
+### Password Issues
+- Verify password is encrypted (contains `:` and is 192 chars)
+- Check `enablePasswordEncryption` is `true` in Manager config
+- Use CLI command for password updates: `npx reldens-cms-update-password`
+- For debugging, set `RELDENS_LOG_LEVEL=9` to see password encryption logs
+
 ## Dependencies
 
 - **@reldens/storage** - Database abstraction layer