underpost 3.2.4 → 3.2.8

package/src/client/ssr/offline/NoNetworkConnection.js

@@ -19,7 +19,7 @@ const main = () => {
         es: 'Volver a  <br> la pagina principal',
       },
     },
-    Render: function (id) {
+    instance: function (id) {
       return this.Data[id][getLang()] ? this.Data[id][getLang()] : this.Data[id]['en'];
     },
   };
@@ -49,9 +49,9 @@ const main = () => {
         ${icon}
         <br />
         <br />
-        <br />${Translate.Render('no-internet-connection')} <br />
+        <br />${Translate.instance('no-internet-connection')} <br />
         <br />
-        <a target="_top" href="${location.origin}">${Translate.Render('back')}</a>
+        <a target="_top" href="${location.origin}">${Translate.instance('back')}</a>
       </div>`,
   );
 };

package/src/client/ssr/pages/Test.js

@@ -15,7 +15,7 @@ const main = () => {
         es: 'Volver a  <br> la pagina principal',
       },
     },
-    Render: function (id) {
+    instance: function (id) {
       return this.Data[id][getLang()] ? this.Data[id][getLang()] : this.Data[id]['en'];
     },
   };
@@ -182,7 +182,7 @@ const main = () => {
         <span class="bold">Test Page</span>
         <br />
         <br />
-        <a target="_top" href="${location.origin}">${Translate.Render('back')}</a>
+        <a target="_top" href="${location.origin}">${Translate.instance('back')}</a>
       </div>`,
   );
 };

package/src/client/sw/core.sw.js

@@ -0,0 +1,212 @@
+// Workbox modules are bundled inline by esbuild — no CDN, no importScripts.
+import { setCacheNameDetails, clientsClaim } from 'workbox-core';
+import { precacheAndRoute, cleanupOutdatedCaches, matchPrecache } from 'workbox-precaching';
+import { registerRoute, setCatchHandler } from 'workbox-routing';
+import { StaleWhileRevalidate, NetworkFirst, NetworkOnly } from 'workbox-strategies';
+import { CacheableResponsePlugin } from 'workbox-cacheable-response';
+import { ExpirationPlugin } from 'workbox-expiration';
+import { BackgroundSyncPlugin } from 'workbox-background-sync';
+
+// ─── Runtime config injected by client-build.js ───────────────────────────────
+const CACHE_PREFIX = self.renderPayload?.CACHE_PREFIX || 'engine-core-v3';
+const PRE_CACHED_RESOURCES = Array.isArray(self.renderPayload?.PRE_CACHED_RESOURCES)
+  ? self.renderPayload.PRE_CACHED_RESOURCES
+  : [];
+const PROXY_PATH = self.renderPayload?.PROXY_PATH || '/';
+const OFFLINE_PATH = self.renderPayload?.OFFLINE_PATH || '/offline';
+const MAINTENANCE_PATH = self.renderPayload?.MAINTENANCE_PATH || '/maintenance';
+const proxyBase = PROXY_PATH === '/' ? '' : PROXY_PATH;
+const normalizeRoutePath = (candidatePath, fallbackPath) => {
+  const routePath = typeof candidatePath === 'string' && candidatePath.length > 0 ? candidatePath : fallbackPath;
+  const withLeadingSlash = routePath.startsWith('/') ? routePath : `/${routePath}`;
+  const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, '');
+  return withoutTrailingSlash.length > 0 ? withoutTrailingSlash : '/';
+};
+const offlinePath = normalizeRoutePath(OFFLINE_PATH, '/offline');
+const maintenancePath = normalizeRoutePath(MAINTENANCE_PATH, '/maintenance');
+const toRouteIndexUrl = (routePath) => `${proxyBase}${routePath === '/' ? '' : routePath}/index.html`;
+const offlineUrl = toRouteIndexUrl(offlinePath);
+const maintenanceUrl = toRouteIndexUrl(maintenancePath);
+
+// Dedicated cache for fallback pages — populated independently from precacheAndRoute
+// so offline/maintenance pages are always available even if the main precache install fails.
+const FALLBACK_CACHE_NAME = `${CACHE_PREFIX}-fallbacks`;
+
+const getFallbackResponse = async (preferMaintenance) => {
+  const cache = await caches.open(FALLBACK_CACHE_NAME);
+  if (preferMaintenance) {
+    return (
+      (await cache.match(maintenanceUrl)) ||
+      (await matchPrecache(maintenanceUrl)) ||
+      (await cache.match(offlineUrl)) ||
+      (await matchPrecache(offlineUrl)) ||
+      Response.error()
+    );
+  }
+  return (
+    (await cache.match(offlineUrl)) ||
+    (await matchPrecache(offlineUrl)) ||
+    (await cache.match(maintenanceUrl)) ||
+    (await matchPrecache(maintenanceUrl)) ||
+    Response.error()
+  );
+};
+
+// ─── Core setup ───────────────────────────────────────────────────────────────
+setCacheNameDetails({ prefix: CACHE_PREFIX });
+clientsClaim();
+
+self.addEventListener('install', (event) => {
+  self.skipWaiting();
+  // Cache fallback pages in a dedicated cache so they are available even if
+  // precacheAndRoute fails (e.g. some asset in the manifest returns non-200).
+  event.waitUntil(
+    caches.open(FALLBACK_CACHE_NAME).then((cache) =>
+      // Try together first; fall back to individual adds so a single failure
+      // does not prevent the other page from being cached.
+      cache
+        .addAll([offlineUrl, maintenanceUrl])
+        .catch(() => Promise.all([cache.add(offlineUrl).catch(() => {}), cache.add(maintenanceUrl).catch(() => {})])),
+    ),
+  );
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    (async () => {
+      if ('navigationPreload' in self.registration) {
+        await self.registration.navigationPreload.enable();
+      }
+    })(),
+  );
+});
+
+self.addEventListener('message', (event) => {
+  const payload = event.data || {};
+
+  if (payload.status === 'skipWaiting') {
+    self.skipWaiting();
+    return;
+  }
+
+  if (payload.status === 'workbox-reset') {
+    event.waitUntil(
+      (async () => {
+        const cacheNames = await caches.keys();
+        await Promise.all(cacheNames.map((cacheName) => caches.delete(cacheName)));
+        if (event.ports && event.ports[0]) {
+          event.ports[0].postMessage({ status: 'workbox-reset-done', deleted: cacheNames.length });
+        }
+      })(),
+    );
+  }
+});
+
+// ─── Precaching ───────────────────────────────────────────────────────────────
+precacheAndRoute(PRE_CACHED_RESOURCES.map((url) => ({ url, revision: null })));
+cleanupOutdatedCaches();
+
+// ─── Static assets: StaleWhileRevalidate ─────────────────────────────────────
+registerRoute(
+  ({ request, url }) =>
+    request.method === 'GET' &&
+    url.origin === self.location.origin &&
+    ['style', 'script', 'font', 'image'].includes(request.destination),
+  new StaleWhileRevalidate({
+    cacheName: `${CACHE_PREFIX}-assets`,
+    plugins: [
+      new CacheableResponsePlugin({
+        statuses: [0, 200],
+      }),
+      new ExpirationPlugin({
+        maxEntries: 350,
+        maxAgeSeconds: 30 * 24 * 60 * 60, // 30 days
+      }),
+    ],
+  }),
+);
+
+// ─── API GET: NetworkFirst with short timeout ─────────────────────────────────
+registerRoute(
+  ({ request, url }) => request.method === 'GET' && url.pathname.includes('/api/'),
+  new NetworkFirst({
+    cacheName: `${CACHE_PREFIX}-api-get`,
+    networkTimeoutSeconds: 5,
+    plugins: [
+      new CacheableResponsePlugin({
+        statuses: [0, 200],
+      }),
+      new ExpirationPlugin({
+        maxEntries: 120,
+        maxAgeSeconds: 5 * 60, // 5 minutes
+      }),
+    ],
+  }),
+);
+
+// ─── API mutations: NetworkOnly + background sync replay ─────────────────────
+registerRoute(
+  ({ request, url }) => request.method !== 'GET' && url.pathname.includes('/api/'),
+  new NetworkOnly({
+    plugins: [
+      new BackgroundSyncPlugin('api-mutation-queue', {
+        maxRetentionTime: 24 * 60, // 24 hours
+      }),
+    ],
+  }),
+);
+
+// ─── Navigation: NetworkFirst with offline fallback ───────────────────────────
+registerRoute(
+  ({ request }) => request.mode === 'navigate',
+  async ({ event }) => {
+    const navigationStrategy = new NetworkFirst({
+      cacheName: `${CACHE_PREFIX}-pages`,
+      networkTimeoutSeconds: 4,
+      plugins: [
+        new CacheableResponsePlugin({
+          statuses: [0, 200],
+        }),
+        new ExpirationPlugin({
+          maxEntries: 60,
+          maxAgeSeconds: 12 * 60 * 60, // 12 hours
+        }),
+      ],
+    });
+
+    // Distinguish server-down (online but unreachable) from no-network (offline).
+    // navigator.onLine is false only when the device has no network at all.
+    const isOnline = () => typeof navigator !== 'undefined' && navigator.onLine !== false;
+
+    try {
+      const preload = await event.preloadResponse;
+      if (preload) {
+        if (preload.status >= 500) {
+          return getFallbackResponse(true);
+        }
+        return preload;
+      }
+
+      const networkResponse = await navigationStrategy.handle({ event, request: event.request });
+      if (networkResponse && networkResponse.status >= 500) {
+        return getFallbackResponse(true);
+      }
+      return networkResponse;
+    } catch (_) {
+      // If device reports it has network but the request failed, it means the
+      // server is unreachable/down → show maintenance. True offline → show offline.
+      return getFallbackResponse(isOnline());
+    }
+  },
+);
+
+// ─── Global catch handler ─────────────────────────────────────────────────────
+setCatchHandler(async ({ request }) => {
+  if (request.mode === 'navigate') {
+    return getFallbackResponse(typeof navigator !== 'undefined' && navigator.onLine !== false);
+  }
+  return new Response(JSON.stringify({ status: 'error', message: 'request failed' }), {
+    status: 503,
+    headers: { 'Content-Type': 'application/json' },
+  });
+});

package/src/index.js

@@ -44,7 +44,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.4';
+  static version = 'v3.2.8';
 
   /**
    * Required Node.js major version

package/src/runtime/express/Dockerfile

@@ -30,11 +30,11 @@ RUN dnf clean all
 RUN node --version
 RUN npm --version
 
-# Create non-root user for secure container execution (cron jobs, init containers)
-# Deployment containers override to root via securityContext when npm install -g is needed
-RUN useradd -m -u 1000 -s /bin/bash dd
+# Install underpost ci/cd cli
+RUN npm install -g underpost
+RUN underpost --version
 
-# Set working directory
+# Create working directory
 WORKDIR /home/dd
 
 # Expose necessary ports

package/src/runtime/lampp/Dockerfile

@@ -1,6 +1,6 @@
 FROM rockylinux:9
 
-# Update and install required packages
+# System packages 
 RUN dnf -y update && \
     dnf -y install epel-release && \
     dnf -y install --allowerasing \
@@ -20,13 +20,14 @@ RUN dnf -y update && \
     perl && \
     dnf clean all
 
-# --- Download and install XAMPP (PHP 8.2)
+
+# Download and install XAMPP (PHP 8.2)
 RUN curl -L -o /tmp/xampp-linux-installer.run "https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/8.2.12/xampp-linux-x64-8.2.12-0-installer.run" && \
     chmod +x /tmp/xampp-linux-installer.run && \
     bash -c "/tmp/xampp-linux-installer.run --mode unattended" && \
     ln -sf /opt/lampp/lampp /usr/bin/lampp
 
-# --- Create /xampp/htdocs (static root) and set permissions
+# Create /xampp/htdocs (static root) and set permissions
 RUN mkdir -p /opt/lampp/htdocs && \
     chown -R root:root /opt/lampp/htdocs && \
     chmod -R a+rX /opt/lampp/htdocs
@@ -47,11 +48,11 @@ RUN dnf clean all
 RUN node --version
 RUN npm --version
 
-# Create non-root user for secure container execution (cron jobs, init containers)
-# Deployment containers override to root via securityContext when npm install -g is needed
-RUN useradd -m -u 1000 -s /bin/bash dd
+# Install underpost CLI 
+RUN npm install -g underpost
+RUN underpost --version
 
-# Set working directory
+# Runtime root expected by startup/build scripts.
 WORKDIR /home/dd
 
 EXPOSE 22

package/src/runtime/wp/Dockerfile

@@ -1,13 +1,12 @@
 FROM rockylinux:9
 
-# Update and install required packages
+# System packages 
 RUN dnf -y update && \
     dnf -y install epel-release && \
     dnf -y install --allowerasing \
     bzip2 \
     sudo \
     curl \
-    unzip \
     net-tools \
     openssh-server \
     nano \
@@ -21,13 +20,13 @@ RUN dnf -y update && \
     perl && \
     dnf clean all
 
-# --- Download and install XAMPP (PHP 8.2)
+# Download and install XAMPP (PHP 8.2)
 RUN curl -L -o /tmp/xampp-linux-installer.run "https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/8.2.12/xampp-linux-x64-8.2.12-0-installer.run" && \
     chmod +x /tmp/xampp-linux-installer.run && \
     bash -c "/tmp/xampp-linux-installer.run --mode unattended" && \
     ln -sf /opt/lampp/lampp /usr/bin/lampp
 
-# --- Create /xampp/htdocs (static root) and set permissions
+# Create /xampp/htdocs (static root) and set permissions
 RUN mkdir -p /opt/lampp/htdocs && \
     chown -R root:root /opt/lampp/htdocs && \
     chmod -R a+rX /opt/lampp/htdocs
@@ -39,25 +38,20 @@ RUN echo 'export PATH="/opt/lampp/bin:/usr/local/bin:${PATH}"' > /etc/profile.d/
 # Provide a no-op sendmail so WP plugins don't error on mail calls
 RUN printf '#!/bin/sh\ncat > /dev/null\n' > /usr/sbin/sendmail && chmod +x /usr/sbin/sendmail
 
+# Install Node.js (includes npm)
+RUN curl -fsSL https://rpm.nodesource.com/setup_24.x | bash - && \
+    dnf install -y nodejs && \
+    dnf clean all
+
 # Install WP-CLI
 RUN curl -sL https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar -o /usr/local/bin/wp && \
     chmod +x /usr/local/bin/wp && \
     wp --info --allow-root
 
-# Install Node.js
-RUN curl -fsSL https://rpm.nodesource.com/setup_24.x | bash -
-RUN dnf install nodejs -y
-RUN dnf clean all
-
-# Verify Node.js and npm versions
-RUN node --version
-RUN npm --version
-
-# Create non-root user for secure container execution (cron jobs, init containers)
-# Deployment containers override to root via securityContext when npm install -g is needed
-RUN useradd -m -u 1000 -s /bin/bash dd
+# Install underpost CLI 
+RUN npm install -g underpost
 
-# Set working directory
+# Runtime root expected by startup/build scripts.
 WORKDIR /home/dd
 
 EXPOSE 22

package/src/server/backup.js

@@ -50,8 +50,7 @@ class BackUp {
     for (const _deployId of deployList.split(',')) {
       const deployId = _deployId.trim();
       if (!deployId) continue;
-
-      const dbCommand = `node bin db ${options.git ? '--git --force-clone ' : ''}--export --primary-pod${clusterFlag} ${deployId}`;
+      const dbCommand = `node bin db ${options.git ? '--git --force-clone ' : ''}--export --primary-pod --preserveUUID${clusterFlag} ${deployId}`;
       const repoCommand = `node bin db --repo-backup${clusterFlag} ${deployId}`;
 
       // Pass GITHUB_TOKEN and GITHUB_USERNAME ephemerally through the SSH command

package/src/server/client-build-docs.js

@@ -324,59 +324,56 @@ const buildApiDocs = async ({
 };
 
 /**
- * Builds JSDoc documentation
+ * Builds API documentation using TypeDoc (generates a modern static site from JSDoc-annotated JS).
+ * Config is read from the base typedoc JSON, merged with runtime values, written to a temporary
+ * file, and deleted after the build — the base config file is never mutated on disk.
  * @function buildJsDocs
  * @memberof clientBuildDocs
- * @param {Object} options - JSDoc build options
+ * @param {Object} options - TypeDoc build options
  * @param {string} options.host - The hostname for the documentation
  * @param {string} options.path - The base path for the documentation
  * @param {Object} options.metadata - Metadata for the documentation
- * @param {string} options.publicClientId - Client ID used to resolve the tutorials/references directory
+ * @param {string} options.publicClientId - Client ID used to resolve the references directory
  * @param {Object} options.docs - Documentation config from server conf
- * @param {string} options.docs.jsJsonPath - Path to the JSDoc JSON config file
+ * @param {string} options.docs.jsJsonPath - Path to the base typedoc JSON config file
+ * @param {string} options.docsDestination - Resolved output path for the generated docs
  */
-const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs }) => {
+const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs, docsDestination }) => {
   const logger = loggerFactory(import.meta);
 
-  const jsDocSourcePath = docs.jsJsonPath;
-  if (!fs.existsSync(jsDocSourcePath)) {
-    logger.warn('jsdoc config not found, skipping', jsDocSourcePath);
+  const typedocConfigPath = docs.jsJsonPath;
+  if (!fs.existsSync(typedocConfigPath)) {
+    logger.warn('typedoc config not found, skipping', typedocConfigPath);
     return;
   }
-  const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
-  logger.info('using jsdoc config', jsDocSourcePath);
+  const baseConfig = JSON.parse(fs.readFileSync(typedocConfigPath, 'utf8'));
+  logger.info('using typedoc config', typedocConfigPath);
 
-  jsDocsConfig.opts.destination = `./public/${host}${path === '/' ? path : `${path}/`}docs/`;
-  jsDocsConfig.opts.theme_opts.title = metadata?.title ? metadata.title : undefined;
-  jsDocsConfig.opts.theme_opts.favicon = `./public/${host}${path === '/' ? '/' : `${path}/`}favicon.ico`;
-
-  const tutorialsPath = `./src/client/public/${publicClientId}/docs/references`;
+  // Build runtime config in memory — never mutate the base config file
+  // tsconfig must be absolute so TypeDoc resolves it regardless of where the
+  // tmp config file is located on disk.
+  const runtimeConfig = {
+    ...baseConfig,
+    tsconfig: fs.realpathSync(baseConfig.tsconfig || './tsconfig.docs.json'),
+    out: docsDestination,
+    name: metadata?.title || baseConfig.name,
+    favicon: `./public/${host}${path === '/' ? '/' : `${path}/`}favicon.ico`,
+  };
 
+  // Include extra reference documents as TypeDoc document pages
+  // TypeDoc 0.28+: option is `projectDocuments`, not `documents`
   if (Array.isArray(docs.references) && docs.references.length > 0) {
-    fs.mkdirSync(tutorialsPath, { recursive: true });
-    for (const refPath of docs.references) {
-      if (fs.existsSync(refPath)) {
-        const fileName = refPath.split('/').pop();
-        fs.copySync(refPath, `${tutorialsPath}/${fileName}`);
-        logger.info('copied reference to tutorials', refPath);
-      }
-    }
+    runtimeConfig.projectDocuments = docs.references.filter((p) => fs.existsSync(p));
+    if (runtimeConfig.projectDocuments.length > 0) logger.info('typedoc documents', runtimeConfig.projectDocuments);
   }
 
-  if (fs.existsSync(tutorialsPath) && fs.readdirSync(tutorialsPath).length > 0) {
-    jsDocsConfig.opts.tutorials = tutorialsPath;
-    if (jsDocsConfig.opts.theme_opts.sections && !jsDocsConfig.opts.theme_opts.sections.includes('Tutorials')) {
-      jsDocsConfig.opts.theme_opts.sections.push('Tutorials');
-    }
-    logger.info('build jsdoc tutorials', tutorialsPath);
-  } else {
-    delete jsDocsConfig.opts.tutorials;
-  }
+  const tmpConfigPath = `.typedoc.tmp.json`;
+  fs.writeFileSync(tmpConfigPath, JSON.stringify(runtimeConfig, null, 2), 'utf8');
+  logger.warn('build typedoc view', docsDestination);
 
-  fs.writeFileSync(jsDocSourcePath, JSON.stringify(jsDocsConfig, null, 4), 'utf8');
-  logger.warn('build jsdoc view', jsDocsConfig.opts.destination);
+  shellExec(`node_modules/.bin/typedoc --options ${tmpConfigPath}`, { silent: true });
 
-  shellExec(`npx jsdoc -c ${jsDocSourcePath}`, { silent: true });
+  fs.removeSync(tmpConfigPath);
 };
 
 /**
@@ -384,17 +381,13 @@ const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs })
  * @function buildCoverage
  * @memberof clientBuildDocs
  * @param {Object} options - Coverage build options
- * @param {string} options.host - The hostname for the coverage
- * @param {string} options.path - The base path for the coverage
  * @param {Object} options.docs - Documentation config from server conf
- * @param {string} options.docs.coveragePath - Directory where to run npm run coverage
+ * @param {string} options.docs.coveragePath - Directory where coverage reports are generated
+ * @param {string} options.docsDestination - Resolved output path where docs were built
  */
-const buildCoverage = async ({ host, path, docs }) => {
+const buildCoverage = async ({ docs, docsDestination }) => {
   const logger = loggerFactory(import.meta);
-  const jsDocSourcePath = docs.jsJsonPath;
-  const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
-  const coveragePath = docs.coveragePath;
-  const coverageOutputDir = docs.coverageOutputDir || 'coverage';
+  const { coveragePath, coverageOutputDir = 'coverage' } = docs;
 
   const coverageOutputPath = `${coveragePath}/coverage`;
   if (!fs.existsSync(coverageOutputPath)) {
@@ -412,7 +405,7 @@ const buildCoverage = async ({ host, path, docs }) => {
   }
 
   if (fs.existsSync(coverageOutputPath) && fs.readdirSync(coverageOutputPath).length > 0) {
-    const coverageBuildPath = `${jsDocsConfig.opts.destination}${coverageOutputDir}`;
+    const coverageBuildPath = `${docsDestination}${coverageOutputDir}`;
     fs.mkdirSync(coverageBuildPath, { recursive: true });
     // Hardhat 3 outputs HTML to coverage/html/; Hardhat 2 / c8 output directly to coverage/
     const coverageHtmlSubdir = `${coverageOutputPath}/html`;
@@ -453,8 +446,14 @@ const buildDocs = async ({
   packageData,
   docs,
 }) => {
-  await buildJsDocs({ host, path, metadata, publicClientId, docs });
-  await buildCoverage({ host, path, docs });
+  const pathPrefix = path === '/' ? '/' : `${path}/`;
+  // TypeDoc output is versioned: served at /docs/engine/{version}/
+  const version = (packageData?.version || '').replace(/^v/, '');
+  const jsDocsDestination = `./public/${host}${pathPrefix}docs/engine/${version}/`;
+  // Coverage output at /docs/coverage/ (or /docs/{coverageOutputDir}/)
+  const coverageBaseDestination = `./public/${host}${pathPrefix}docs/`;
+  await buildJsDocs({ host, path, metadata, publicClientId, docs, docsDestination: jsDocsDestination });
+  await buildCoverage({ docs, docsDestination: coverageBaseDestination });
   await buildApiDocs({
     host,
     path,