underpost 2.99.4 → 2.99.5

package/examples/static-page/README.md

@@ -1,406 +1,83 @@
-# Underpost Static Site Generator - Examples
+# Static Page Example
 
-This directory contains comprehensive examples and documentation for the Underpost Static Site Generator.
-
-## Contents
-
-### Documentation
-
-- **[STATIC-GENERATOR-GUIDE.md](./STATIC-GENERATOR-GUIDE.md)** - Complete guide covering all features, best practices, and advanced usage patterns
-
-### Configuration Examples
-
-- **[static-config-example.json](./static-page/static-config-example.json)** - Fully documented configuration file template with all available options
-
-### SSR Component Examples
-
-- **[ssr-components/CustomPage.js](./ssr-components/CustomPage.js)** - Complete example of a custom landing page with:
-  - Semantic HTML structure
-  - Accessibility features
-  - Responsive design
-  - Progressive enhancement
-  - Inline critical CSS
-  - Interactive JavaScript
+Generate static HTML pages using the `underpost static` CLI.
 
 ## Quick Start
 
-### 1. Generate a Config Template
-
-```bash
-underpost static --generate-config ./my-static-config.json
-```
-
-This creates a template configuration file with all available options documented.
-
-### 2. Customize Your Config
-
-Edit the generated config file with your specific requirements:
-
-```json
-{
-  "page": "./src/client/ssr/body/YourPage.js",
-  "outputPath": "./dist/index.html",
-  "metadata": {
-    "title": "Your App Title",
-    "description": "Your app description"
-  }
-}
-```
-
-### 3. Build Your Static Page
-
-```bash
-underpost static --config-file ./my-static-config.json
-```
-
-## Example Usage Scenarios
-
-### Basic Static Page
-
-```bash
-underpost static \
-  --page ./src/client/ssr/body/DefaultSplashScreen.js \
-  --output-path ./dist/index.html \
-  --title "My App"
-```
-
-### Landing Page with SEO
-
-```bash
-underpost static \
-  --page ./examples/static-page/ssr-components/CustomPage.js \
-  --output-path ./dist/landing.html \
-  --title "Welcome to My App" \
-  --description "The best app for your needs" \
-  --keywords "app,solution,innovation" \
-  --theme-color "#667eea" \
-  --canonical-url "https://myapp.com"
-```
-
-### Complete Customization
-
-Use the provided `static-config-example.json`:
-
-```bash
-# Copy the example
-cp ./examples/static-page/static-config-example.json ./my-config.json
-
-# Edit with your settings
-nano ./my-config.json
-
-# Build
-underpost static --config-file ./my-config.json
-```
-
-## Available Examples
-
-### 1. Complete Configuration Example
-
-**File:** `static-config-example.json`
-
-**What it demonstrates:**
-- Complete metadata configuration
-- Script injection (head and body)
-- Stylesheet management
-- Icon configuration
-- SSR component inclusion
-- Microdata/structured data
-- Custom payload injection
-
-**Use case:** Production-ready web application with full SEO and PWA support
-
-### 2. Custom Landing Page Component
-
-**File:** `ssr-components/CustomPage.js`
-
-**What it demonstrates:**
-- Hero section with call-to-action
-- Feature showcase grid
-- Content sections
-- Contact form
-- Footer with links
-- Responsive design
-- Accessibility features
-- Progressive enhancement
-
-**Use case:** Marketing landing page or product showcase
-
-## Configuration Options Reference
-
-### Metadata Options
-
-```json
-{
-  "metadata": {
-    "title": "Page title",
-    "description": "SEO description",
-    "keywords": ["keyword1", "keyword2"],
-    "author": "Author name",
-    "themeColor": "#ffffff",
-    "canonicalURL": "https://example.com",
-    "thumbnail": "https://example.com/image.png",
-    "locale": "en-US",
-    "siteName": "Site Name"
-  }
-}
-```
-
-### Script Options
-
-```json
-{
-  "scripts": {
-    "head": [
-      {
-        "src": "https://cdn.example.com/script.js",
-        "async": true,
-        "integrity": "sha384-...",
-        "crossorigin": "anonymous"
-      },
-      {
-        "content": "window.config = {};",
-        "type": "text/javascript"
-      }
-    ],
-    "body": [
-      {
-        "src": "/app.js",
-        "type": "module",
-        "defer": true
-      }
-    ]
-  }
-}
+```sh
+# From the project root directory:
+underpost static --page ./examples/static-page/ssr-components/CustomPage.js \
+                 --output-path ./public/default.net/example.html
 ```
 
-### Style Options
+## Using a Config File
 
-```json
-{
-  "styles": [
-    { "href": "/main.css" },
-    { "content": "body { margin: 0; }" },
-    { "href": "/print.css", "media": "print" }
-  ]
-}
-```
+A JSON config file lets you define all options in one place instead of passing CLI flags.
 
-### Icon Options
+**Generate a starter config:**
 
-```json
-{
-  "icons": {
-    "favicon": "/favicon.ico",
-    "appleTouchIcon": "/apple-touch-icon.png",
-    "manifest": "/manifest.json",
-    "additional": [
-      {
-        "rel": "icon",
-        "type": "image/png",
-        "sizes": "32x32",
-        "href": "/favicon-32x32.png"
-      }
-    ]
-  }
-}
+```sh
+underpost static --generate-config ./static-config.json
 ```
 
-### Component Options
+**Build from the included example config:**
 
-```json
-{
-  "headComponents": [
-    "./src/client/ssr/head/Seo.js",
-    "./src/client/ssr/head/Pwa.js"
-  ],
-  "bodyComponents": [
-    "./src/client/ssr/body/Header.js"
-  ]
-}
+```sh
+underpost static --config-file ./examples/static-page/static-config-example.json
 ```
 
-### Structured Data (Microdata)
+## Config File Reference
 
-```json
-{
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "WebSite",
-      "name": "My Site",
-      "url": "https://example.com"
-    }
-  ]
-}
-```
+See [`static-config-example.json`](./static-config-example.json) for a complete working example.
 
-## Common Use Cases
+| Field | Type | Description |
+|-------|------|-------------|
+| `page` | `string` | Path to the SSR component to render |
+| `outputPath` | `string` | Output HTML file path |
+| `env` | `string` | `"production"` or `"development"` |
+| `minify` | `boolean` | Minify HTML output |
+| `lang` | `string` | HTML `lang` attribute |
+| `dir` | `string` | HTML `dir` attribute (`ltr`/`rtl`) |
+| `metadata` | `object` | SEO metadata (title, description, keywords, author, themeColor, canonicalURL, thumbnail, locale, siteName) |
+| `scripts` | `object` | `{ head: [...], body: [...] }` — inline or external scripts |
+| `styles` | `array` | Inline (`content`) or external (`href`) stylesheets |
+| `icons` | `object` | `favicon`, `appleTouchIcon`, `manifest` paths |
+| `headComponents` | `array` | SSR component paths injected into `<head>` |
+| `bodyComponents` | `array` | SSR component paths injected into `<body>` |
+| `microdata` | `array` | JSON-LD structured data objects |
+| `customPayload` | `object` | Arbitrary data injected into the render payload |
 
-### 1. Simple Blog Post
-
-```json
-{
-  "page": "./src/client/ssr/body/BlogPost.js",
-  "outputPath": "./dist/blog/my-post.html",
-  "metadata": {
-    "title": "My Blog Post Title",
-    "description": "Summary of the blog post",
-    "author": "John Doe",
-    "keywords": ["blogging", "tutorial"]
-  },
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "BlogPosting",
-      "headline": "My Blog Post Title",
-      "author": {
-        "@type": "Person",
-        "name": "John Doe"
-      },
-      "datePublished": "2024-01-01"
-    }
-  ]
-}
-```
+## CLI Flags
 
-### 2. E-commerce Product Page
+Flags override config file values when both are provided.
 
-```json
-{
-  "page": "./src/client/ssr/body/ProductPage.js",
-  "outputPath": "./dist/products/widget.html",
-  "metadata": {
-    "title": "Premium Widget - Buy Now",
-    "description": "High-quality widget with free shipping",
-    "thumbnail": "https://shop.com/widget.jpg"
-  },
-  "microdata": [
-    {
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "name": "Premium Widget",
-      "offers": {
-        "@type": "Offer",
-        "price": "29.99",
-        "priceCurrency": "USD"
-      }
-    }
-  ]
-}
+```sh
+underpost static --page <path>            # SSR component path
+                 --output-path <path>     # Output file
+                 --config-file <path>     # JSON config file
+                 --env <env>              # production | development
+                 --minify / --no-minify   # Toggle minification
+                 --title <title>          # Page title
+                 --description <text>     # Meta description
+                 --keywords <a,b,c>       # Comma-separated keywords
+                 --author <name>          # Meta author
+                 --favicon <path>         # Favicon path
+                 --lang <lang>            # HTML lang attribute
+                 --dir <dir>              # HTML dir attribute
+                 --dev                    # Development mode
 ```
 
-### 3. Documentation Page
+## SSR Component
 
-```json
-{
-  "page": "./src/client/ssr/body/DocsPage.js",
-  "outputPath": "./dist/docs/index.html",
-  "headComponents": [
-    "./src/client/ssr/head/Seo.js"
-  ],
-  "styles": [
-    { "href": "/docs/prism.css" },
-    { "href": "/docs/docs.css" }
-  ],
-  "scripts": {
-    "body": [
-      { "src": "/docs/prism.js", "defer": true },
-      { "src": "/docs/search.js", "defer": true }
-    ]
-  }
-}
-```
-
-### 4. Multi-language Pages
+The page content is defined in an SSR component file. See [`ssr-components/CustomPage.js`](./ssr-components/CustomPage.js) for an example.
 
-```bash
-# English version
-underpost static --config-file ./config-en.json --lang en --dir ltr
+A component exports an `SrrComponent` function that returns an HTML template literal:
 
-# Spanish version
-underpost static --config-file ./config-es.json --lang es --dir ltr
-
-# Arabic version
-underpost static --config-file ./config-ar.json --lang ar --dir rtl
-```
-
-## Best Practices
-
-### 1. SEO Optimization
-
-✅ Always include title, description, and keywords
-✅ Use canonical URLs
-✅ Add Open Graph metadata
-✅ Include structured data (JSON-LD)
-✅ Optimize images in metadata
-
-### 2. Performance
-
-✅ Minify HTML in production
-✅ Use async/defer for scripts
-✅ Inline critical CSS
-✅ Optimize asset loading order
-
-### 3. Accessibility
-
-✅ Use semantic HTML
-✅ Include ARIA labels
-✅ Ensure keyboard navigation
-✅ Test with screen readers
-
-### 4. Progressive Enhancement
-
-✅ Ensure content works without JavaScript
-✅ Add interactive features progressively
-✅ Test on various devices
-✅ Provide fallbacks
-
-## Advanced Techniques
-
-### Custom SSR Component Template
-
-```javascript
-/**
- * Custom Component Template
- * @description Brief description of the component
- */
+```js
 SrrComponent = () => html`
-  <div class="custom-component">
-    <!-- Your HTML here -->
+  <div>
+    <h1>Hello World</h1>
+    <p>Your page content here.</p>
   </div>
-  
-  <style>
-    /* Component-specific styles */
-  </style>
-  
-  <script>
-    // Component-specific JavaScript
-    document.addEventListener('DOMContentLoaded', function() {
-      // Your code here
-    });
-  </script>
 `;
 ```
-
-### Programmatic Usage
-
-```javascript
-import UnderpostStatic from './src/cli/static.js';
-
-// Generate multiple pages
-const pages = [
-  { slug: 'home', title: 'Home' },
-  { slug: 'about', title: 'About' },
-  { slug: 'contact', title: 'Contact' }
-];
-
-for (const page of pages) {
-  await UnderpostStatic.API.callback({
-    page: `./src/client/ssr/body/${page.slug}.js`,
-    outputPath: `./dist/${page.slug}.html`,
-    metadata: {
-      title: page.title
-    }
-  });
-}
-```

package/examples/static-page/ssr-components/CustomPage.js

@@ -1,22 +1,10 @@
 /**
  * Custom Page SSR Component Example
  * @module examples/ssr-components/CustomPage
- *
- * @description
- * This is an example SSR component demonstrating best practices for creating
- * custom static pages with the Underpost Static Site Generator.
  */
 
 /**
- * Main SSR Component for rendering a custom landing page
- *
- * This component demonstrates:
- * - Semantic HTML structure
- * - Accessibility best practices
- * - Responsive design patterns
- * - Progressive enhancement
- * - Clean, maintainable code
- *
+ * SSR Component Example for rendering a custom landing page
  * @function SrrComponent
  * @returns {string} HTML string for the page body
  */

package/manifests/deployment/dd-default-development/deployment.yaml

@@ -17,7 +17,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-blue
-          image: localhost/rockylinux9-underpost:v2.99.4
+          image: localhost/rockylinux9-underpost:v2.99.5
           #          resources:
           #            requests:
           #              memory: "124Ki"
@@ -100,7 +100,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-green
-          image: localhost/rockylinux9-underpost:v2.99.4
+          image: localhost/rockylinux9-underpost:v2.99.5
           #          resources:
           #            requests:
           #              memory: "124Ki"

package/manifests/deployment/dd-test-development/deployment.yaml

@@ -18,7 +18,7 @@ spec:
     spec:
       containers:
         - name: dd-test-development-blue
-          image: localhost/rockylinux9-underpost:v2.99.4
+          image: localhost/rockylinux9-underpost:v2.99.5
 
           command:
             - /bin/sh
@@ -103,7 +103,7 @@ spec:
     spec:
       containers:
         - name: dd-test-development-green
-          image: localhost/rockylinux9-underpost:v2.99.4
+          image: localhost/rockylinux9-underpost:v2.99.5
 
           command:
             - /bin/sh

package/package.json

@@ -2,7 +2,7 @@
     "type": "module",
     "main": "src/index.js",
     "name": "underpost",
-    "version": "2.99.4",
+    "version": "2.99.5",
     "description": "pwa api rest template",
     "scripts": {
         "start": "env-cmd -f .env.production node --max-old-space-size=8192 src/server",
@@ -22,7 +22,7 @@
         "install": "npm run install-global && npm run install-test",
         "prettier": "prettier --write .",
         "fix": "npm audit fix --force && npm audit",
-        "baremetal": "node bin baremetal --dev --commission --clear-discovered --remove-machines all --ls --create-machine"
+        "baremetal": "node bin baremetal --dev --commission --ls --create-machine"
     },
     "bin": {
         "underpost": "bin/index.js"

package/scripts/disk-devices.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# disk-devices.sh
+# List block devices with detailed info, including by-id names
+# Usage: sudo ./disk-devices.sh
+set -euo pipefail
+
+sudo bash -c 'printf "NODE\tTYPE\tSIZE\tFSTYPE\tLABEL\tUUID\tMOUNTPOINT\tBY-ID\n"; \
+lsblk -pnl -o NAME,TYPE,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINT | while read -r DEV TYPE SIZE FS LBL UUID MNT; do \
+    node=$(readlink -f "$DEV"); \
+    byid=$(find /dev/disk/by-id/ -maxdepth 1 -lname "*${node##*/}" ! -name "nvme-eui*" ! -name "dm-uuid*" 2>/dev/null | head -n 1); \
+    [ -z "$byid" ] && byid=$(find /dev/disk/by-id/ -maxdepth 1 -lname "*${node##*/}" 2>/dev/null | head -n 1); \
+    printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" "$node" "$TYPE" "$SIZE" "$FS" "$LBL" "$UUID" "$MNT" "$(basename "$byid" 2>/dev/null)"; \
+done' | column -s $'\t' -t