@reldens/cms 0.47.0 → 0.49.0

package/.claude/installation-guide.md

@@ -0,0 +1,223 @@
+# Advanced Installation Guide
+
+## Subprocess Installation Handling
+
+The installer supports complex operations through subprocess management:
+
+```javascript
+const { Installer } = require('@reldens/cms');
+
+const installer = new Installer({
+    projectRoot: process.cwd(),
+    subprocessMaxAttempts: 1800,
+    postInstallCallback: async (props) => {
+        console.log('Entities loaded:', Object.keys(props.loadedEntities.rawRegisteredEntities));
+        return true;
+    }
+});
+```
+
+**The installer automatically handles:**
+
+- Package dependency checking and installation
+- Database schema creation via subprocess
+- Prisma client generation with progress tracking
+- Entity generation with validation
+- Environment file creation
+- Directory structure setup
+
+## Enhanced Manager Initialization
+
+The Manager class provides comprehensive service initialization:
+
+```javascript
+const cms = new Manager({
+    app: customExpressApp,
+    appServer: customAppServer,
+    dataServer: customDataServer,
+    adminManager: customAdmin,
+    frontend: customFrontend,
+    adminRoleId: 99,
+    authenticationMethod: 'db-users',
+    authenticationCallback: async (email, password, roleId) => {
+        return await yourAuthService.validate(email, password, roleId);
+    },
+    cache: true,
+    reloadTime: -1,
+    defaultDomain: 'example.com',
+    domainMapping: {'dev.example.com': 'development'},
+    siteKeyMapping: {'example.com': 'main'}
+});
+```
+
+**Manager automatically:**
+
+- Validates all provided instances
+- Initializes missing services
+- Sets up entity access control
+- Generates admin entities
+- Configures template reloading
+
+## Development Mode Detection
+
+The CMS automatically detects development environments based on domain patterns.
+
+**Default Development Patterns:**
+
+```javascript
+const patterns = [
+    'localhost',
+    '127.0.0.1',
+    '.local',
+    '.test',
+    '.dev',
+    '.acc',
+    '.staging',
+    'local.',
+    'test.',
+    'dev.',
+    'acc.',
+    'staging.'
+];
+```
+
+**Override Development Patterns:**
+
+```javascript
+const cms = new Manager({
+    developmentPatterns: [
+        'localhost',
+        '127.0.0.1',
+        '.local'
+    ],
+    domainMapping: {
+        'www.example.com': 'example.com',
+        'new.example.com': 'example.com'
+    }
+});
+```
+
+**Important Notes:**
+
+- Domain patterns only match at the start or end of domains, not arbitrary positions
+- Override `developmentPatterns` in production to prevent staging/acc domains from enabling development mode
+
+## Security Configuration
+
+### External Domains for CSP
+
+Configure external domains for CSP directives (kebab-case or camelCase):
+
+```javascript
+const cms = new Manager({
+    appServerConfig: {
+        developmentExternalDomains: {
+            'scriptSrc': ['https://cdn.example.com'],
+            'script-src': ['https://analytics.example.com'],
+            'styleSrc': ['https://fonts.googleapis.com'],
+            'font-src': ['https://fonts.gstatic.com']
+        }
+    }
+});
+```
+
+**The system automatically:**
+
+- Converts kebab-case keys to camelCase
+- Adds domains to both the base directive and the -elem variant
+
+### CSP Directive Merging vs Override
+
+**Default (merge with base directives):**
+
+```javascript
+const cms = new Manager({
+    appServerConfig: {
+        helmetConfig: {
+            contentSecurityPolicy: {
+                directives: {
+                    scriptSrc: ['https://cdn.example.com']
+                }
+            }
+        }
+    }
+});
+```
+
+**Default Base Directives:**
+
+```javascript
+{
+    defaultSrc: ["'self'"],
+    scriptSrc: ["'self'"],
+    scriptSrcElem: ["'self'"],
+    styleSrc: ["'self'", "'unsafe-inline'"],
+    styleSrcElem: ["'self'", "'unsafe-inline'"],
+    imgSrc: ["'self'", "data:", "https:"],
+    fontSrc: ["'self'"],
+    connectSrc: ["'self'"],
+    frameAncestors: ["'none'"],
+    baseUri: ["'self'"],
+    formAction: ["'self'"]
+}
+```
+
+**Complete Replacement:**
+
+```javascript
+const cms = new Manager({
+    appServerConfig: {
+        helmetConfig: {
+            contentSecurityPolicy: {
+                overrideDirectives: true,
+                directives: {
+                    defaultSrc: ["'self'"],
+                    scriptSrc: ["'self'", "https://trusted-cdn.com"],
+                    styleSrc: ["'self'", "'unsafe-inline'"],
+                    imgSrc: ["'self'", "data:", "https:"],
+                    fontSrc: ["'self'"],
+                    connectSrc: ["'self'"],
+                    frameAncestors: ["'none'"],
+                    baseUri: ["'self'"],
+                    formAction: ["'self'"]
+                }
+            }
+        }
+    }
+});
+```
+
+### Additional Helmet Security Headers
+
+```javascript
+const cms = new Manager({
+    appServerConfig: {
+        helmetConfig: {
+            hsts: {
+                maxAge: 31536000,
+                includeSubDomains: true,
+                preload: true
+            },
+            crossOriginOpenerPolicy: {
+                policy: "same-origin"
+            },
+            crossOriginResourcePolicy: {
+                policy: "same-origin"
+            },
+            crossOriginEmbedderPolicy: {
+                policy: "require-corp"
+            }
+        }
+    }
+});
+```
+
+**Note:** In development mode, CSP and HSTS are automatically disabled. Security headers are only enforced in production.
+
+**Trusted Types:** To enable Trusted Types for enhanced XSS protection:
+
+```javascript
+requireTrustedTypesFor: ["'script'"]
+```
+
+However, this requires updating all JavaScript code to use the Trusted Types API.

package/.claude/multi-domain-i18n-guide.md

@@ -0,0 +1,178 @@
+# Multi-Domain and Internationalization Guide
+
+## Internationalization
+
+### Translation Files
+
+Create translation files in the `translations` directory:
+
+**translations/en.json:**
+
+```json
+{
+  "navigation": {
+    "home": "Home",
+    "about": "About Us",
+    "contact": "Contact"
+  },
+  "messages": {
+    "welcome": "Welcome to our site!",
+    "greeting": "Hello {name}!"
+  }
+}
+```
+
+**translations/es.json:**
+
+```json
+{
+  "navigation": {
+    "home": "Inicio",
+    "about": "Acerca de",
+    "contact": "Contacto"
+  },
+  "messages": {
+    "welcome": "¡Bienvenido a nuestro sitio!",
+    "greeting": "¡Hola {name}!"
+  }
+}
+```
+
+### Using Translations in Templates
+
+```html
+[translate(navigation.home)]
+[t(navigation.home, Home)]
+[t(messages.greeting, Hello!, {name: John})]
+```
+
+Locale detection from request headers or ?locale=es parameter.
+
+## Multi-Domain Setup
+
+### Directory Structure
+
+```
+templates/
+├── layouts/
+│   ├── default.html
+│   ├── full-width.html
+│   └── minimal.html
+├── domains/
+│   ├── example.com/
+│   │   ├── layouts/
+│   │   ├── partials/
+│   │   │   ├── header.html
+│   │   │   └── footer.html
+│   │   ├── cms_forms/
+│   │   │   ├── form.html
+│   │   │   └── field_text.html
+│   │   ├── page.html
+│   │   └── index.html
+│   └── dev.example.com/
+│       └── page.html
+├── partials/
+│   ├── header.html (default)
+│   └── footer.html (default)
+├── cms_forms/
+│   ├── form.html
+│   ├── field_text.html
+│   └── field_email.html
+├── translations/
+│   ├── en.json
+│   ├── es.json
+│   └── fr.json
+├── page.html (base HTML wrapper)
+└── 404.html
+```
+
+### Template Resolution Order
+
+1. Domain-specific: `templates/domains/{domain}/template.html`
+2. Default: `templates/template.html`
+3. Base: Package default templates
+
+### Configuration
+
+```javascript
+const cms = new Manager({
+    defaultDomain: 'example.com',
+    domainMapping: {'dev.example.com': 'development'},
+    siteKeyMapping: {'example.com': 'main'}
+});
+```
+
+## Layout System
+
+The CMS uses a two-tier 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"/>
+```
+
+**Available Layouts:**
+
+Pages can use different layouts by setting the `layout` field in `cms_pages`:
+
+- `default` - Header, sidebar, main content, footer
+- `full-width` - Full width without sidebars
+- `minimal` - Basic layout with minimal styling
+
+## 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>');
+```
+
+## Entity Access Control
+
+Control which entities are publicly accessible:
+
+```javascript
+const cms = new Manager({
+    entityAccess: {
+        articles: { public: true, operations: ['read'] },
+        cmsPages: { public: true, operations: ['read'] },
+        users: { public: false }
+    }
+});
+```