underpost 2.90.1 → 2.90.4

package/README.md

@@ -18,7 +18,7 @@
 
 <!-- badges -->
 
-[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/2.90.1)](https://socket.dev/npm/package/underpost/overview/2.90.1) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
+[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/2.90.4)](https://socket.dev/npm/package/underpost/overview/2.90.4) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
 
 <!-- end-badges -->
 
@@ -66,7 +66,7 @@ Run dev client server
 npm run dev
 ```
 <!-- -->
-## underpost ci/cd cli v2.90.1
+## underpost ci/cd cli v2.90.4
 
 ### Usage: `underpost [options] [command]`
   ```
@@ -82,7 +82,7 @@ Commands:
   cmt [options] [path] [commit-type] [module-tag] [message]  Manages commits to a GitHub repository, supporting various commit types and options.
   push [options] <path> <uri>                                Pushes committed changes from a local repository to a remote GitHub repository.
   env [deploy-id] [env] [subConf]                            Sets environment variables and configurations related to a specific deployment ID.
-  static [options]                                           Manages static build of page, bundles, and documentation.
+  static [options]                                           Manages static build of page, bundles, and documentation with comprehensive customization options.
   config [options] <operator> [key] [value]                  Manages Underpost configurations using various operators.
   root                                                       Displays the root path of the npm installation.
   ip [options]                                               Displays the current public machine IP addresses.

package/bin/deploy.js

@@ -1237,6 +1237,22 @@ nvidia/gpu-operator \
       break;
     }
 
+    case 'update-static-guide': {
+      fs.writeFileSync(
+        `src/client/public/nexodev/docs/references/Static Site Generator Quick Reference.md`,
+        fs.readFileSync(`examples/QUICK-REFERENCE.md`, 'utf8'),
+      );
+      fs.writeFileSync(
+        `src/client/public/nexodev/docs/references/Static Site Generator Examples.md`,
+        fs.readFileSync(`examples/README.md`, 'utf8'),
+      );
+      fs.writeFileSync(
+        `src/client/public/nexodev/docs/references/Static Generator Guide.md`,
+        fs.readFileSync(`examples/STATIC-GENERATOR-GUIDE.md`, 'utf8'),
+      );
+      break;
+    }
+
     case 'udpate-version-files': {
       const oldNpmVersion = process.argv[3];
       const oldNodeVersion = process.argv[4];

package/cli.md

@@ -1,4 +1,4 @@
-## underpost ci/cd cli v2.90.1
+## underpost ci/cd cli v2.90.4
 
 ### Usage: `underpost [options] [command]`
   ```
@@ -14,7 +14,7 @@ Commands:
   cmt [options] [path] [commit-type] [module-tag] [message]  Manages commits to a GitHub repository, supporting various commit types and options.
   push [options] <path> <uri>                                Pushes committed changes from a local repository to a remote GitHub repository.
   env [deploy-id] [env] [subConf]                            Sets environment variables and configurations related to a specific deployment ID.
-  static [options]                                           Manages static build of page, bundles, and documentation.
+  static [options]                                           Manages static build of page, bundles, and documentation with comprehensive customization options.
   config [options] <operator> [key] [value]                  Manages Underpost configurations using various operators.
   root                                                       Displays the root path of the npm installation.
   ip [options]                                               Displays the current public machine IP addresses.
@@ -199,13 +199,33 @@ Options:
 ```
  Usage: underpost static [options]
 
-Manages static build of page, bundles, and documentation.
+Manages static build of page, bundles, and documentation with comprehensive
+customization options.
 
 Options:
   --page <ssr-component-path>  Build custom static pages.
-  --title <title>              Sets a custom title for the static page.
+  --title <title>              Sets a custom title for the static page
+                               (deprecated: use --config-file).
   --output-path <output-path>  Sets the output path for the generated static
                                page.
+  --description <description>  Page description for SEO.
+  --keywords <keywords>        Comma-separated keywords for SEO.
+  --author <author>            Page author.
+  --theme-color <color>        Theme color for mobile browsers.
+  --canonical-url <url>        Canonical URL for SEO.
+  --thumbnail <url>            Open Graph thumbnail image URL.
+  --locale <locale>            Page locale (default: en-US).
+  --site-name <name>           Site name for Open Graph.
+  --head-scripts <paths>       Comma-separated paths to scripts for head
+                               section.
+  --body-scripts <paths>       Comma-separated paths to scripts for body
+                               section.
+  --styles <paths>             Comma-separated paths to stylesheets.
+  --favicon <path>             Favicon path.
+  --apple-touch-icon <path>    Apple touch icon path.
+  --manifest <path>            Web manifest path.
+  --head-components <paths>    Comma-separated SSR head component paths.
+  --body-components <paths>    Comma-separated SSR body component paths.
   --deploy-id <deploy-id>      Build static assets for a specific deployment
                                ID.
   --build                      Triggers the static build process for the
@@ -216,6 +236,13 @@ Options:
                                assets.
   --env <env>                  Sets the environment for the static build (e.g.,
                                "development", "production").
+  --minify                     Minify HTML output (default: true for
+                               production).
+  --no-minify                  Disable HTML minification.
+  --config-file <path>         Path to JSON configuration file.
+  --generate-config [path]     Generate a template configuration file.
+  --lang <lang>                HTML lang attribute (default: en).
+  --dir <dir>                  HTML dir attribute (default: ltr).
   --dev                        Sets the development cli context
   -h, --help                   display help for command
  
@@ -733,7 +760,6 @@ Options:
   --limits-memory <limits-memory>                 Sets memory limit for the runner execution.
   --limits-cpu <limits-cpu>                       Sets CPU limit for the runner execution.
   --resource-template-id <resource-template-id >  Specifies a resource template ID for the runner execution.
-  --etcHosts                                      Enables /etc/hosts management for the runner execution.
   --expose                                        Enables service exposure for the runner execution.
   --conf-server-path <conf-server-path>           Sets a custom configuration server path.
   --underpost-root <underpost-root>               Sets a custom Underpost root path.

package/examples/QUICK-REFERENCE.md

@@ -0,0 +1,499 @@
+# 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" }
+  ]
+}
+```
+
+## Documentation Links
+
+- [Complete Guide](./STATIC-GENERATOR-GUIDE.md)
+- [Example Config](./static-config-example.json)
+- [Custom Component Example](./ssr-components/CustomPage.js)
+- [Examples README](./README.md)
+
+## Tips
+
+✅ Use config files for complex setups
+✅ Minify in production
+✅ Use async/defer for scripts
+✅ Include structured data for SEO
+✅ Test on multiple devices
+✅ Validate your JSON configs
+✅ Use semantic HTML in components
+✅ Include accessibility attributes