@underpostnet/underpost 2.99.4 → 2.99.5

package/src/server/logger.js

@@ -28,11 +28,13 @@ const levels = {
   debug: 4,
 };
 
-// This method set the current severity based on
-// the current NODE_ENV: show all the log levels
-// if the server was run in development mode; otherwise,
-// if it was run in production, show only warn and error messages.
-const level = () => 'info'; // (process.env.NODE_ENV || 'development' ? 'debug' : 'warn');
+/**
+ * The `level` function determines the logging level based on the provided `logLevel` parameter or defaults to 'info'.
+ * @param {string} logLevel - The logging level to be used. If not provided, it defaults to 'info'.
+ * @returns {string} The logging level to be used for the logger.
+ * @memberof Logger
+ */
+const level = (logLevel = '') => logLevel || 'info';
 
 // Define different colors for each level.
 // Colors make the log message more visible,
@@ -98,13 +100,14 @@ const setUpInfo = async (logger = new winston.Logger()) => {
  * messages.
  * @param meta - The `meta` parameter in the `loggerFactory` function is used to extract the last part
  * of a URL and use it to create log files in a specific directory.
+ * @param logLevel - Specify the logging level for the logger instance. e.g., 'error', 'warn', 'info', 'debug'.
  * @returns {underpostLogger} The `loggerFactory` function returns a logger instance created using Winston logger
  * library. The logger instance is configured with various transports for printing out messages to
  * different destinations such as the terminal, error.log file, and all.log file. The logger instance
  * also has a method `setUpInfo` attached to it for setting up additional information.
  * @memberof Logger
  */
-const loggerFactory = (meta = { url: '' }) => {
+const loggerFactory = (meta = { url: '' }, logLevel = '') => {
   meta = meta.url.split('/').pop();
   // Define which transports the logger must use to print out messages.
   // In this example, we are using three different transports
@@ -125,7 +128,7 @@ const loggerFactory = (meta = { url: '' }) => {
   // and used to log messages.
   const logger = winston.createLogger({
     defaultMeta: meta,
-    level: level(),
+    level: level(logLevel),
     levels,
     format: format(meta),
     transports,
@@ -147,38 +150,30 @@ const loggerFactory = (meta = { url: '' }) => {
 };
 
 /**
- * The `loggerMiddleware` function creates a middleware for logging HTTP requests using Morgan with
- * custom message format and options.
- * @param meta - The `meta` parameter in the `loggerMiddleware` function is an object that contains
- * information about the request URL. It has a default value of an empty object `{ url: '' }`. This
- * object is used to provide additional metadata for logging purposes.
- * @returns {Handler<any, any>} The `loggerMiddleware` function returns a middleware function that uses the Morgan library
- * to log HTTP request information. The middleware function formats the log message using predefined
- * tokens provided by Morgan and custom tokens like `:host` to include specific request details. The
- * log message format includes information such as remote address, HTTP method, host, URL, status code,
- * content length, and response time in milliseconds. The middleware
+ * The `loggerMiddleware` function is an Express middleware that uses the Morgan library to log HTTP requests.
+ * @param {Object} meta - An object containing metadata, such as the URL, to be used in the logger.
+ * @param {string} logLevel - The logging level to be used for the logger (e.g., 'error', 'warn', 'info', 'debug').
+ * @param {Function} skip - A function to determine whether to skip logging for a particular request.
+ * @returns {Function} A middleware function that can be used in an Express application to log HTTP requests.
  * @memberof Logger
  */
-const loggerMiddleware = (meta = { url: '' }) => {
+const loggerMiddleware = (
+  meta = { url: '' },
+  logLevel = 'info',
+  skip = (req, res) => process.env.NODE_ENV === 'production',
+) => {
   const stream = {
     // Use the http severity
-    write: (message) => loggerFactory(meta).http(message),
+    write: (message) => loggerFactory(meta, logLevel).http(message),
   };
 
-  const skip = (req, res) => process.env.NODE_ENV === 'production';
-
   morgan.token('host', function (req, res) {
     return req.headers['host'];
   });
 
   return morgan(
-    // Define message format string (this is the default one).
-    // The message format is made from tokens, and each token is
-    // defined inside the Morgan library.
-    // You can create your custom token to show what do you want from a request.
+    // Define message format string
     `:remote-addr :method :host:url :status :res[content-length] - :response-time ms`,
-    // Options: in this case, I overwrote the stream and the skip logic.
-    // See the methods above.
     { stream, skip },
   );
 };

package/src/server/tls.js

@@ -1,7 +1,7 @@
 /**
- * @class UnderpostTls
- * @description TLS/SSL utilities for Underpost.
- * @memberof UnderpostTls
+ * Transport Layer Security (TLS) / SSL utilities and HTTPS server creation and management.
+ * @module src/server/tls.js
+ * @namespace UnderpostTLS
  */
 
 import fs from 'fs-extra';
@@ -42,7 +42,7 @@ class TLS {
    * It attempts to be permissive: accepts cert-only, cert+ca, or fullchain.
    * @param {string} host
    * @returns {{key?:string, cert?:string, fullchain?:string, ca?:string, dir:string}}
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static locateSslFiles(host = DEFAULT_HOST) {
     const dir = SSL_BASE(host);
@@ -102,7 +102,7 @@ class TLS {
    * Validate that a secure context can be built for host (key + cert or fullchain present)
    * @param {string} host
    * @returns {boolean}
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static validateSecureContext(host = DEFAULT_HOST) {
     const files = TLS.locateSslFiles(host);
@@ -115,7 +115,7 @@ class TLS {
    * If separate cert + ca are found, they will be used accordingly.
    * @param {string} host
    * @returns {{key:string, cert:string, ca?:string}} options
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static buildSecureContext(host = DEFAULT_HOST) {
     const files = TLS.locateSslFiles(host);
@@ -141,7 +141,7 @@ class TLS {
    * The function will copy existing discovered files to: key.key, crt.crt, ca_bundle.crt when possible.
    * @param {string} host
    * @returns {boolean} true if at least key+cert exist after operation
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static async buildLocalSSL(host = DEFAULT_HOST) {
     const dir = SSL_BASE(host);
@@ -176,7 +176,7 @@ class TLS {
    * @param {import('express').Application} app
    * @param {Object<string, any>} hosts
    * @returns {{ServerSSL?: https.Server}}
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static async createSslServer(app, hosts = { [DEFAULT_HOST]: {} }) {
     let server;
@@ -214,7 +214,7 @@ class TLS {
    * @param {number} port
    * @param {Object<string, any>} proxyRouter
    * @returns {import('express').RequestHandler}
-   * @memberof UnderpostTls
+   * @memberof UnderpostTLS
    */
   static sslRedirectMiddleware(req, res, port = 80, proxyRouter = {}) {
     const sslRedirectUrl = `https://${req.headers.host}${req.url}`;
@@ -235,11 +235,11 @@ class TLS {
 }
 
 /**
- * @class UnderpostTls
+ * @class UnderpostTLS
  * @description TLS/SSL utilities for Underpost.
- * @memberof UnderpostTls
+ * @memberof UnderpostTLS
  */
-class UnderpostTls {
+class UnderpostTLS {
   static API = {
     TLS,
     SSL_BASE,
@@ -252,5 +252,5 @@ class UnderpostTls {
   };
 }
 
-export { TLS, SSL_BASE, UnderpostTls };
-export default UnderpostTls;
+export { TLS, SSL_BASE, UnderpostTLS };
+export default UnderpostTLS;

package/examples/static-page/QUICK-REFERENCE.md

@@ -1,481 +0,0 @@
-# Underpost Static Site Generator - Quick Reference
-
-## Basic Commands
-
-### Generate Config Template
-```bash
-underpost static --generate-config ./static-config.json
-```
-
-### Build from Config File
-```bash
-underpost static --config-file ./static-config.json
-```
-
-### Simple Page Generation
-```bash
-underpost static \
-  --page ./src/client/ssr/body/Page.js \
-  --output-path ./dist/index.html \
-  --title "My Page"
-```
-
-## Common CLI Patterns
-
-### Landing Page with SEO
-```bash
-underpost static \
-  --page ./src/client/ssr/body/Landing.js \
-  --output-path ./dist/landing.html \
-  --title "Welcome" \
-  --description "My awesome landing page" \
-  --keywords "landing,web,app" \
-  --theme-color "#007bff" \
-  --canonical-url "https://example.com"
-```
-
-### Page with External Scripts
-```bash
-underpost static \
-  --page ./src/client/ssr/body/App.js \
-  --output-path ./dist/app.html \
-  --head-scripts "https://cdn.example.com/analytics.js" \
-  --body-scripts "/app.js,/vendor.js"
-```
-
-### Page with Custom Icons
-```bash
-underpost static \
-  --page ./src/client/ssr/body/Home.js \
-  --output-path ./dist/index.html \
-  --favicon "/favicon.ico" \
-  --apple-touch-icon "/apple-touch-icon.png" \
-  --manifest "/manifest.json"
-```
-
-### Production Build with Deployment
-```bash
-underpost static \
-  --page ./src/client/ssr/body/App.js \
-  --output-path ./public/index.html \
-  --deploy-id "production-v1" \
-  --build-host "example.com" \
-  --build-path "/" \
-  --build \
-  --env production
-```
-
-## Configuration File Patterns
-
-### Minimal Config
-```json
-{
-  "page": "./src/client/ssr/body/Page.js",
-  "outputPath": "./dist/index.html",
-  "metadata": {
-    "title": "My Page",
-    "description": "Page description"
-  }
-}
-```
-
-### SEO-Optimized Config
-```json
-{
-  "page": "./src/client/ssr/body/Page.js",
-  "outputPath": "./dist/index.html",
-  "metadata": {
-    "title": "My SEO Page",
-    "description": "Comprehensive description for SEO",
-    "keywords": ["seo", "optimization", "web"],
-    "author": "Your Name",
-    "canonicalURL": "https://example.com",
-    "thumbnail": "https://example.com/og-image.png",
-    "themeColor": "#4CAF50"
-  }
-}
-```
-
-### With Scripts and Styles
-```json
-{
-  "page": "./src/client/ssr/body/Page.js",
-  "outputPath": "./dist/index.html",
-  "scripts": {
-    "head": [
-      { "src": "https://cdn.example.com/lib.js", "async": true }
-    ],
-    "body": [
-      { "src": "/app.js", "type": "module", "defer": true }
-    ]
-  },
-  "styles": [
-    { "href": "/main.css" },
-    { "content": "body { margin: 0; }" }
-  ]
-}
-```
-
-### PWA Configuration
-```json
-{
-  "page": "./src/client/ssr/body/App.js",
-  "outputPath": "./dist/index.html",
-  "metadata": {
-    "title": "My PWA",
-    "themeColor": "#007bff"
-  },
-  "icons": {
-    "favicon": "/favicon.ico",
-    "appleTouchIcon": "/apple-touch-icon.png",
-    "manifest": "/manifest.json"
-  },
-  "scripts": {
-    "body": [
-      {
-        "content": "if('serviceWorker' in navigator){navigator.serviceWorker.register('/sw.js');}"
-      }
-    ]
-  }
-}
-```
-
-### With Structured Data
-```json
-{
-  "page": "./src/client/ssr/body/Page.js",
-  "outputPath": "./dist/index.html",
-  "metadata": {
-    "title": "My Product"
-  },
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "name": "My Product",
-      "offers": {
-        "@type": "Offer",
-        "price": "29.99",
-        "priceCurrency": "USD"
-      }
-    }
-  ]
-}
-```
-
-## SSR Component Patterns
-
-### Basic Component
-```javascript
-SrrComponent = () => html`
-  <div class="page">
-    <h1>Hello World</h1>
-  </div>
-`;
-```
-
-### Component with Styles
-```javascript
-SrrComponent = () => html`
-  <div class="custom-page">
-    <h1>Styled Page</h1>
-  </div>
-  <style>
-    .custom-page {
-      padding: 20px;
-    }
-  </style>
-`;
-```
-
-### Component with JavaScript
-```javascript
-SrrComponent = () => html`
-  <div class="interactive-page">
-    <button id="myButton">Click Me</button>
-  </div>
-  <script>
-    document.addEventListener('DOMContentLoaded', function() {
-      document.getElementById('myButton').addEventListener('click', function() {
-        alert('Button clicked!');
-      });
-    });
-  </script>
-`;
-```
-
-### Component with Dynamic Content
-```javascript
-SrrComponent = () => html`
-  <div class="dynamic-page">
-    <h1>Current Year: ${new Date().getFullYear()}</h1>
-    <p>Generated at: ${new Date().toISOString()}</p>
-  </div>
-`;
-```
-
-## Environment-Specific Builds
-
-### Development
-```bash
-underpost static \
-  --config-file ./config.json \
-  --env development \
-  --no-minify \
-  --dev
-```
-
-### Production
-```bash
-underpost static \
-  --config-file ./config.json \
-  --env production \
-  --minify
-```
-
-## Multi-Page Generation
-
-### Using Script (Bash)
-```bash
-#!/bin/bash
-PAGES=("home" "about" "contact")
-
-for page in "${PAGES[@]}"; do
-  underpost static \
-    --page "./src/client/ssr/body/${page}.js" \
-    --output-path "./dist/${page}.html" \
-    --title "$(echo $page | sed 's/.*/\u&/')"
-done
-```
-
-### Using JavaScript
-```javascript
-import UnderpostStatic from './src/cli/static.js';
-
-const pages = ['home', 'about', 'contact'];
-
-for (const page of pages) {
-  await UnderpostStatic.API.callback({
-    page: `./src/client/ssr/body/${page}.js`,
-    outputPath: `./dist/${page}.html`,
-    metadata: {
-      title: page.charAt(0).toUpperCase() + page.slice(1)
-    }
-  });
-}
-```
-
-## Metadata Patterns
-
-### Blog Post
-```json
-{
-  "metadata": {
-    "title": "How to Build Static Sites",
-    "description": "A comprehensive guide to building static sites",
-    "keywords": ["static", "guide", "tutorial"],
-    "author": "Jane Doe"
-  },
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "BlogPosting",
-      "headline": "How to Build Static Sites",
-      "author": { "@type": "Person", "name": "Jane Doe" },
-      "datePublished": "2024-01-01"
-    }
-  ]
-}
-```
-
-### E-commerce Product
-```json
-{
-  "metadata": {
-    "title": "Premium Widget - $29.99",
-    "description": "High-quality widget with free shipping",
-    "thumbnail": "https://shop.com/widget.jpg"
-  },
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "name": "Premium Widget",
-      "image": "https://shop.com/widget.jpg",
-      "offers": {
-        "@type": "Offer",
-        "price": "29.99",
-        "priceCurrency": "USD",
-        "availability": "https://schema.org/InStock"
-      }
-    }
-  ]
-}
-```
-
-### Organization
-```json
-{
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "Organization",
-      "name": "My Company",
-      "url": "https://example.com",
-      "logo": "https://example.com/logo.png",
-      "sameAs": [
-        "https://twitter.com/mycompany",
-        "https://linkedin.com/company/mycompany"
-      ]
-    }
-  ]
-}
-```
-
-## JavaScript API Usage
-
-### Basic Generation
-```javascript
-import UnderpostStatic from './src/cli/static.js';
-
-await UnderpostStatic.API.callback({
-  page: './src/client/ssr/body/Page.js',
-  outputPath: './dist/index.html',
-  metadata: { title: 'My Page' }
-});
-```
-
-### Using Template Helpers
-```javascript
-import { TemplateHelpers } from './src/cli/static.js';
-
-const scriptTag = TemplateHelpers.createScriptTag({
-  src: '/app.js',
-  defer: true,
-  type: 'module'
-});
-
-const metaTags = TemplateHelpers.createMetaTags({
-  title: 'My Page',
-  description: 'Description',
-  keywords: ['key1', 'key2']
-});
-```
-
-### Validation
-```javascript
-import { ConfigValidator } from './src/cli/static.js';
-
-const result = ConfigValidator.validate(options);
-if (!result.isValid) {
-  console.error('Errors:', result.errors);
-}
-```
-
-## Common Script Snippets
-
-### Google Analytics
-```json
-{
-  "scripts": {
-    "head": [
-      {
-        "src": "https://www.googletagmanager.com/gtag/js?id=GA_ID",
-        "async": true
-      },
-      {
-        "content": "window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','GA_ID');"
-      }
-    ]
-  }
-}
-```
-
-### Service Worker Registration
-```json
-{
-  "scripts": {
-    "body": [
-      {
-        "content": "if('serviceWorker' in navigator){navigator.serviceWorker.register('/sw.js').then(reg=>console.log('SW registered',reg)).catch(err=>console.log('SW error',err));}"
-      }
-    ]
-  }
-}
-```
-
-### App Configuration
-```json
-{
-  "scripts": {
-    "head": [
-      {
-        "content": "window.appConfig={apiUrl:'https://api.example.com',version:'1.0.0',features:{analytics:true,debugging:false}};"
-      }
-    ]
-  }
-}
-```
-
-## Troubleshooting Quick Fixes
-
-### Component Not Found
-```bash
-# Check if file exists
-ls -la ./src/client/ssr/body/Page.js
-
-# Use absolute path from project root
-underpost static --page ./src/client/ssr/body/Page.js --output-path ./dist/index.html
-```
-
-### Invalid JSON Config
-```bash
-# Validate JSON
-cat config.json | python -m json.tool
-
-# Or use jq
-jq . config.json
-```
-
-### Output Directory Missing
-```bash
-# Create directory first
-mkdir -p ./dist/pages
-
-# Then run command
-underpost static --config-file ./config.json
-```
-
-## Performance Optimization
-
-### Minification
-```json
-{
-  "env": "production",
-  "minify": true
-}
-```
-
-### Async Loading
-```json
-{
-  "scripts": {
-    "head": [
-      { "src": "/analytics.js", "async": true }
-    ],
-    "body": [
-      { "src": "/app.js", "defer": true }
-    ]
-  }
-}
-```
-
-### Critical CSS
-```json
-{
-  "styles": [
-    { "content": "body{margin:0;font-family:sans-serif}" },
-    { "href": "/main.css" }
-  ]
-}
-```