@underpostnet/underpost 3.0.0 → 3.0.1

package/.env.development

@@ -40,5 +40,4 @@ DEFAULT_ADMIN_EMAIL=admin@default.net
 DEFAULT_ADMIN_PASSWORD=changethis
 DEFAULT_SSH_PORT=22
 BASE_API=api
-DEV_PROXY_PORT_OFFSET=200
-ENABLE_FILE_LOGS=true
+DEV_PROXY_PORT_OFFSET=200

package/.env.test

@@ -40,5 +40,4 @@ DEFAULT_ADMIN_EMAIL=admin@default.net
 DEFAULT_ADMIN_PASSWORD=changethis
 DEFAULT_SSH_PORT=22
 BASE_API=api
-DEV_PROXY_PORT_OFFSET=200
-ENABLE_FILE_LOGS=true
+DEV_PROXY_PORT_OFFSET=200

package/.github/workflows/gitlab.ci.yml

@@ -0,0 +1,20 @@
+name: CI | Publish gitlab repository package
+on: [push]
+jobs:
+  pwa-microservices-template:
+    if: github.repository == 'underpostnet/pwa-microservices-template' && startsWith(github.event.head_commit.message, 'ci(package-pwa-microservices-template-ghpkg)')
+    name: Update gitlab repo package Jobs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Push to GitLab
+        run: |
+          git remote add gitlab https://oauth2:${{ secrets.GITLAB_TOKEN }}@gitlab.com/underpostnet/pwa-microservices-template.git
+          git lfs install
+          git lfs fetch --all
+          git lfs push --all gitlab
+          git push gitlab HEAD:main --force
+          git push gitlab --force --tags

package/CHANGELOG.md

@@ -1,6 +1,55 @@
 # Changelog
 
-## 2026-02-22
+## 2026-02-23
+
+### gitlab
+
+- Fix package json lock template build ([e674ec6b](https://github.com/underpostnet/engine/commit/e674ec6be61d7a170ab468d473d0e545401b765a))
+- Fix mirror push to GitLab ([9585aa50](https://github.com/underpostnet/engine/commit/9585aa50ee481fa49084c0edd44cc28b4b2561e8))
+
+### bin-file
+
+- Add missing gitlab.ci.yml build to pwa-microservices-template ([ec49ded0](https://github.com/underpostnet/engine/commit/ec49ded0ac3fbfcba1e7e10b0ed1dcfc13a8da87))
+
+### client-core
+
+- Add missing keyboard focus search box on iframes docs ([c5b0f86c](https://github.com/underpostnet/engine/commit/c5b0f86c7acc0d2c964cc1ef80625693241e6d62))
+- Add VanillaJs get selector in iframe ([e37fa340](https://github.com/underpostnet/engine/commit/e37fa34037cff9924bc747f1ee11190ee2e1164b))
+
+### giblab
+
+- Add .gitlab-ci.yml ([a795bd5f](https://github.com/underpostnet/engine/commit/a795bd5f3526257c858ec70ee27feb8bfd793baf))
+
+### docs
+
+- Add VanillaJs get selector in iframe sync darkTheme in docs component. ([5b2ba08f](https://github.com/underpostnet/engine/commit/5b2ba08f3b0df3a6072aa49ca55efd223f72a95c))
+
+### server-client-build-docs
+
+- Enable Swagger UI Dark Light Mode ([eaadad70](https://github.com/underpostnet/engine/commit/eaadad70cd74bcd9f7990dd63834bbd69bffcbae))
+
+### github-actions
+
+- Add gitlab mirror CI repository integration ([3d6acdef](https://github.com/underpostnet/engine/commit/3d6acdefeea72f26a733975e822dbcf2b4e793e3))
+- Fix GitHub Actions npm provenance ([cd31b8f0](https://github.com/underpostnet/engine/commit/cd31b8f0ed202ed376016d3fc4b9fc63152f5186))
+
+### cli-run
+
+- Fix missing cluster type on runners id cluster and gpu env ([ddd72d2e](https://github.com/underpostnet/engine/commit/ddd72d2e32e448b8956862f0719d5ab2d2ea7606))
+
+### package
+
+- Resolve npm ci lock mismatch ([357b4e81](https://github.com/underpostnet/engine/commit/357b4e81611541a0d979bc95cb587343bf540604))
+
+### cli-repo
+
+- Fix Changelog error due to type integration message ([750656e1](https://github.com/underpostnet/engine/commit/750656e1cbee5dbb3e73d9d5cdd4d94ed049a4f1))
+
+### cli-ipfs
+
+- Fix underpost ipfs syntax import in main src index ([f7bebb65](https://github.com/underpostnet/engine/commit/f7bebb6555a85df35aed3e248dd0b304c00fd008))
+
+## New release v:3.0.0 (2026-02-22)
 
 ### engine-core
 

package/CLI-HELP.md

@@ -1,4 +1,4 @@
-## underpost ci/cd cli v3.0.0
+## underpost ci/cd cli v3.0.1
 
 ### Usage: `underpost [options] [command]`
   ```

package/README.md

@@ -16,7 +16,7 @@
 
 <div align="center">
 
-[![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/3.0.0)](https://socket.dev/npm/package/underpost/overview/3.0.0) [![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/3.0.1)](https://socket.dev/npm/package/underpost/overview/3.0.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)
 
 </div>
 
@@ -60,7 +60,7 @@ npm run dev
 
 <a target="_top" href="https://www.nexodev.org/docs?cid=src">See Docs here.</a>
 
-## underpost ci/cd cli v3.0.0
+## underpost ci/cd cli v3.0.1
 
 ### Usage: `underpost [options] [command]`
   ```

package/bin/file.js

@@ -86,7 +86,7 @@ try {
         // fs.copySync(`./.github`, `../pwa-microservices-template/.github`);
         fs.copySync(`./src/client/public/default`, `../pwa-microservices-template/src/client/public/default`);
 
-        for (const checkoutPath of ['README.md', 'package-lock.json', 'package.json'])
+        for (const checkoutPath of ['README.md', 'package.json'])
           shellExec(`cd ../pwa-microservices-template && git checkout ${checkoutPath}`);
 
         for (const deletePath of [
@@ -110,6 +110,7 @@ try {
           `./.github/workflows/pwa-microservices-template-test.ci.yml`,
           `./.github/workflows/npmpkg.ci.yml`,
           `./.github/workflows/ghpkg.ci.yml`,
+          `./.github/workflows/gitlab.ci.yml`,
           `./.github/workflows/publish.ci.yml`,
           `./.github/workflows/release.cd.yml`,
           './src/ws/IoInterface.js',
@@ -129,6 +130,7 @@ try {
         templatePackageJson.devDependencies = originPackageJson.devDependencies;
         templatePackageJson.version = originPackageJson.version;
         templatePackageJson.scripts = originPackageJson.scripts;
+        templatePackageJson.overrides = originPackageJson.overrides;
         templatePackageJson.name = name;
         templatePackageJson.description = description;
         // templatePackageJson.scripts.dev = dev;
@@ -142,15 +144,17 @@ try {
           JSON.stringify(templatePackageJson, null, 4),
           'utf8',
         );
-
         const originPackageLockJson = JSON.parse(fs.readFileSync('./package-lock.json', 'utf8'));
+
         const templatePackageLockJson = JSON.parse(
           fs.readFileSync('../pwa-microservices-template/package-lock.json', 'utf8'),
         );
+
         const originBasePackageLock = newInstance(templatePackageLockJson.packages['']);
+        templatePackageLockJson.name = name;
         templatePackageLockJson.version = originPackageLockJson.version;
         templatePackageLockJson.packages = originPackageLockJson.packages;
-        templatePackageLockJson.packages[''].name = originBasePackageLock.name;
+        templatePackageLockJson.packages[''].name = name;
         templatePackageLockJson.packages[''].version = originPackageLockJson.version;
         templatePackageLockJson.packages[''].hasInstallScript = originBasePackageLock.hasInstallScript;
         templatePackageLockJson.packages[''].license = originBasePackageLock.license;
@@ -159,6 +163,8 @@ try {
           JSON.stringify(templatePackageLockJson, null, 4),
           'utf8',
         );
+        // Regenerate package-lock.json to match the modified package.json
+        // shellExec(`cd ../pwa-microservices-template && npm install --package-lock-only --ignore-scripts`);
         fs.writeFileSync(
           '../pwa-microservices-template/README.md',
           fs

package/manifests/cronjobs/dd-cron/dd-cron-backup.yaml

@@ -23,7 +23,7 @@ spec:
         spec:
           containers:
             - name: dd-cron-backup
-              image: underpost/underpost-engine:v3.0.0
+              image: underpost/underpost-engine:v3.0.1
               command:
                 - /bin/sh
                 - -c

package/manifests/cronjobs/dd-cron/dd-cron-dns.yaml

@@ -23,7 +23,7 @@ spec:
         spec:
           containers:
             - name: dd-cron-dns
-              image: underpost/underpost-engine:v3.0.0
+              image: underpost/underpost-engine:v3.0.1
               command:
                 - /bin/sh
                 - -c

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

@@ -17,7 +17,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-blue
-          image: localhost/rockylinux9-underpost:v3.0.0
+          image: localhost/rockylinux9-underpost:v3.0.1
           #          resources:
           #            requests:
           #              memory: "124Ki"
@@ -100,7 +100,7 @@ spec:
     spec:
       containers:
         - name: dd-default-development-green
-          image: localhost/rockylinux9-underpost:v3.0.0
+          image: localhost/rockylinux9-underpost:v3.0.1
           #          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:v3.0.0
+          image: localhost/rockylinux9-underpost:v3.0.1
 
           command:
             - /bin/sh
@@ -103,7 +103,7 @@ spec:
     spec:
       containers:
         - name: dd-test-development-green
-          image: localhost/rockylinux9-underpost:v3.0.0
+          image: localhost/rockylinux9-underpost:v3.0.1
 
           command:
             - /bin/sh

package/package.json

@@ -2,7 +2,7 @@
     "type": "module",
     "main": "src/index.js",
     "name": "@underpostnet/underpost",
-    "version": "3.0.0",
+    "version": "3.0.1",
     "description": "pwa api rest template",
     "scripts": {
         "start": "env-cmd -f .env.production node --max-old-space-size=8192 src/server",
@@ -108,5 +108,9 @@
         "provenance": true,
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "overrides": {
+        "minimatch": "^10.2.2",
+        "glob": "^11.0.0"
     }
 }

package/src/api/user/user.router.js

@@ -99,22 +99,6 @@ const UserRouter = (options) => {
     #swagger.description = 'This endpoint get a JWT for authenticated user'
     #swagger.path = '/user/auth'
     #swagger.method = 'post'
-    #swagger.produces = ['application/json']
-    #swagger.consumes = ['application/json']
-
-    #swagger.requestBody = {
-      in: 'body',
-      description: 'User data',
-      required: true,
-      content: {
-          'application/json': {
-              schema: {
-                  $ref: '#/components/schemas/userLogInRequest'
-              }
-          }
-      }
-    }
-
     #swagger.responses[200] = {
       description: 'User created successfully',
       content: {
@@ -148,22 +132,6 @@ const UserRouter = (options) => {
       #swagger.description = 'This endpoint will create a new user account'
       #swagger.path = '/user'
       #swagger.method = 'post'
-      #swagger.produces = ['application/json']
-      #swagger.consumes = ['application/json']
-
-      #swagger.requestBody = {
-        in: 'body',
-        description: 'User data',
-        required: true,
-        content: {
-            'application/json': {
-                schema: {
-                    $ref: '#/components/schemas/userRequest'
-                }
-            }
-        }
-      }
-
       #swagger.responses[200] = {
         description: 'User created successfully',
         content: {
@@ -274,8 +242,6 @@ const UserRouter = (options) => {
       #swagger.description = 'This endpoint will update user data by ID'
       #swagger.path = '/user/{id}'
       #swagger.method = 'put'
-      #swagger.produces = ['application/json']
-      #swagger.consumes = ['application/json']
       #swagger.security = [{
         'bearerAuth': []
       }]
@@ -287,19 +253,6 @@ const UserRouter = (options) => {
           type: 'string'
       }
 
-      #swagger.requestBody = {
-        in: 'body',
-        description: 'User data',
-        required: true,
-        content: {
-            'application/json': {
-                schema: {
-                  $ref: '#/components/schemas/userRequest'
-                }
-            }
-        }
-      }
-
       #swagger.responses[200] = {
         description: 'User updated successfully',
         content: {

package/src/cli/lxd.js

@@ -344,7 +344,7 @@ ipv6.address=none`);
         }
         case 'dev-reset': {
           shellExec(
-            `lxc exec ${vmName} -- bash -lc 'cd /home/dd/engine && node bin cluster --dev --reset && node bin cluster --dev --k3s'`,
+            `lxc exec ${vmName} -- bash -lc 'cd /home/dd/engine && node bin cluster --dev --reset --k3s && node bin cluster --dev --k3s'`,
           );
           break;
         }

package/src/cli/run.js

@@ -1148,7 +1148,7 @@ EOF
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const clusterType = options.k3s ? 'k3s' : 'kubeadm';
       shellCd(`/home/dd/engine`);
-      shellExec(`${baseCommand} cluster${baseClusterCommand} --reset`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --reset --${clusterType}`);
       await timer(5000);
       shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType}`);
       await timer(5000);
@@ -1779,8 +1779,9 @@ EOF
      * @memberof UnderpostRun
      */
     'gpu-env': (path, options = DEFAULT_OPTION) => {
+      const clusterType = 'kubeadm';
       shellExec(
-        `node bin cluster --dev --reset && node bin cluster --dev --dedicated-gpu --kubeadm && kubectl get pods --all-namespaces -o wide -w`,
+        `node bin cluster --dev --reset --${clusterType} && node bin cluster --dev --dedicated-gpu --${clusterType} && kubectl get pods --all-namespaces -o wide -w`,
       );
     },
     /**

package/src/client/components/core/Docs.js

@@ -1,9 +1,9 @@
 import { Badge } from './Badge.js';
 import { BtnIcon } from './BtnIcon.js';
-import { Css, renderCssAttr, simpleIconsRender, ThemeEvents, Themes } from './Css.js';
+import { Css, darkTheme, renderCssAttr, simpleIconsRender, ThemeEvents, Themes } from './Css.js';
 import { buildBadgeToolTipMenuOption, Modal, renderViewTitle } from './Modal.js';
 import { listenQueryPathInstance, setQueryPath, closeModalRouteChangeEvent, getProxyPath } from './Router.js';
-import { htmls, s } from './VanillaJs.js';
+import { htmls, s, sIframe } from './VanillaJs.js';
 
 // https://mintlify.com/docs/quickstart
 
@@ -39,6 +39,7 @@ const Docs = {
       RouterInstance: Modal.Data['modal-docs'].options.RouterInstance,
     });
     const iframeEl = s(`.iframe-${ModalId}`);
+    let swaggerThemeEventKey = null;
     if (iframeEl) {
       iframeEl.addEventListener('load', () => {
         try {
@@ -51,7 +52,95 @@ const Docs = {
           // cross-origin or security restriction — safe to ignore
         }
         window.scrollTo(0, 0);
+        // Bind Shift+K inside the iframe to focus the parent SearchBox (mirrors app-wide shortcut)
+        try {
+          const iframeDoc = iframeEl.contentDocument || iframeEl.contentWindow?.document;
+          if (iframeDoc) {
+            iframeDoc.addEventListener('keydown', (e) => {
+              if (e.shiftKey && e.key.toLowerCase() === 'k') {
+                e.preventDefault();
+                e.stopPropagation();
+                if (s(`.top-bar-search-box`)) {
+                  if (s(`.main-body-btn-ui-close`) && s(`.main-body-btn-ui-close`).classList.contains('hide')) {
+                    s(`.main-body-btn-ui-open`).click();
+                  }
+                  s(`.top-bar-search-box`).blur();
+                  s(`.top-bar-search-box`).focus();
+                  s(`.top-bar-search-box`).select();
+                }
+              }
+            });
+          }
+        } catch (e) {
+          // cross-origin or security restriction — safe to ignore
+        }
       });
+
+      if (type === 'src') {
+        swaggerThemeEventKey = `jsdocs-iframe-${ModalId}`;
+
+        const applyJsDocsTheme = (isDark) => {
+          try {
+            const iframeWin = iframeEl.contentWindow;
+            if (!iframeWin) return;
+            const theme = isDark ? 'dark' : 'light';
+            if (typeof iframeWin.updateTheme === 'function') {
+              // clean-jsdoc-theme exposes updateTheme() globally
+              iframeWin.updateTheme(theme);
+            } else {
+              // Fallback: replicate localUpdateTheme manually
+              const iframeDoc = iframeEl.contentDocument || iframeWin.document;
+              if (!iframeDoc || !iframeDoc.body) return;
+              iframeDoc.body.setAttribute('data-theme', theme);
+              iframeDoc.body.classList.remove('dark', 'light');
+              iframeDoc.body.classList.add(theme);
+              const iconID = isDark ? '#light-theme-icon' : '#dark-theme-icon';
+              const svgUses = sIframe(iframeEl, '.theme-svg-use') ? iframeDoc.querySelectorAll('.theme-svg-use') : [];
+              svgUses.forEach((svg) => svg.setAttribute('xlink:href', iconID));
+              iframeWin.localStorage?.setItem('theme', theme);
+            }
+          } catch (e) {
+            // cross-origin or security restriction — safe to ignore
+          }
+        };
+
+        // Apply current theme as soon as the iframe content is ready
+        iframeEl.addEventListener('load', () => applyJsDocsTheme(darkTheme));
+
+        // Keep in sync whenever the parent page theme changes
+        ThemeEvents[swaggerThemeEventKey] = () => {
+          if (s(`.iframe-${ModalId}`)) applyJsDocsTheme(darkTheme);
+        };
+      }
+
+      if (type === 'api') {
+        swaggerThemeEventKey = `swagger-iframe-${ModalId}`;
+
+        const applySwaggerTheme = (isDark) => {
+          try {
+            const iframeDoc = iframeEl.contentDocument || iframeEl.contentWindow?.document;
+            if (!iframeDoc || !iframeDoc.body) return;
+            if (isDark) {
+              iframeDoc.body.classList.add('swagger-dark');
+            } else {
+              iframeDoc.body.classList.remove('swagger-dark');
+            }
+            iframeEl.contentWindow?.localStorage?.setItem('swagger-theme', isDark ? 'dark' : 'light');
+            const toggleBtn = sIframe(iframeEl, '#swagger-theme-toggle');
+            if (toggleBtn) toggleBtn.textContent = isDark ? '\u2600\uFE0F Light Mode' : '\uD83C\uDF19 Dark Mode';
+          } catch (e) {
+            // cross-origin or security restriction — safe to ignore
+          }
+        };
+
+        // Apply current theme as soon as the iframe content is ready
+        iframeEl.addEventListener('load', () => applySwaggerTheme(darkTheme));
+
+        // Keep in sync whenever the parent page theme changes
+        ThemeEvents[swaggerThemeEventKey] = () => {
+          if (s(`.iframe-${ModalId}`)) applySwaggerTheme(darkTheme);
+        };
+      }
     }
     Modal.Data[ModalId].onObserverListener[ModalId] = () => {
       if (s(`.iframe-${ModalId}`)) {
@@ -67,6 +156,7 @@ const Docs = {
     };
     Modal.Data[ModalId].onObserverListener[ModalId]();
     Modal.Data[ModalId].onCloseListener[ModalId] = () => {
+      if (swaggerThemeEventKey) delete ThemeEvents[swaggerThemeEventKey];
       closeModalRouteChangeEvent({ closedId: ModalId });
     };
   },
@@ -342,10 +432,6 @@ const Docs = {
         <div class="docs-landing">
           <div class="docs-header">
             <h1>Documentation</h1>
-            <p>
-              Find everything you need to build amazing applications with our platform. Get started with our guides, API
-              reference, and examples.
-            </p>
             <!--
                     <div class="search-bar">
                       <i class="fas fa-search"></i>

package/src/client/components/core/VanillaJs.js

@@ -418,12 +418,48 @@ function hexToRgbA(hex) {
 
 const htmlStrSanitize = (str) => (str ? str.replace(/<\/?[^>]+(>|$)/g, '').trim() : '');
 
+/**
+ * Query selector inside an iframe. Allows obtaining a single element that is
+ * inside an iframe in order to execute events on it.
+ * Note: the iframe must be same-origin for this to work.
+ *
+ * @param {string|Element} iframeEl The CSS selector string or the iframe Element itself.
+ * @param {string} el The query selector for the element inside the iframe.
+ * @returns {Element|null} The matched element inside the iframe, or null if not found.
+ * @memberof VanillaJS
+ */
+const sIframe = (iframeEl, el) => {
+  const iframe = typeof iframeEl === 'string' ? s(iframeEl) : iframeEl;
+  if (!iframe) return null;
+  const iframeDoc = iframe.contentDocument || iframe.contentWindow?.document;
+  return iframeDoc ? iframeDoc.querySelector(el) : null;
+};
+
+/**
+ * Query selector all inside an iframe. Allows obtaining all elements matching a
+ * selector that are inside an iframe in order to execute events on them.
+ * Note: the iframe must be same-origin for this to work.
+ *
+ * @param {string|Element} iframeEl The CSS selector string or the iframe Element itself.
+ * @param {string} el The query selector for the elements inside the iframe.
+ * @returns {NodeList|null} A NodeList of matched elements inside the iframe, or null if not found.
+ * @memberof VanillaJS
+ */
+const saIframe = (iframeEl, el) => {
+  const iframe = typeof iframeEl === 'string' ? s(iframeEl) : iframeEl;
+  if (!iframe) return null;
+  const iframeDoc = iframe.contentDocument || iframe.contentWindow?.document;
+  return iframeDoc ? iframeDoc.querySelectorAll(el) : null;
+};
+
 export {
   s,
   htmls,
   append,
   prepend,
   sa,
+  sIframe,
+  saIframe,
   copyData,
   pasteData,
   preHTML,

package/src/index.js

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

package/src/runtime/express/Express.js

@@ -20,6 +20,7 @@ import { createPeerServer } from '../../server/peer.js';
 import { createValkeyConnection } from '../../server/valkey.js';
 import { applySecurity, authMiddlewareFactory } from '../../server/auth.js';
 import { ssrMiddlewareFactory } from '../../server/ssr.js';
+import { buildSwaggerUiOptions } from '../../server/client-build-docs.js';
 
 import { shellExec } from '../../server/process.js';
 import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/conf.js';
@@ -167,8 +168,8 @@ class ExpressService {
       // Swagger UI setup
       if (fs.existsSync(swaggerJsonPath)) {
         const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
-        // Reusing swaggerPath defined outside, removing unnecessary redeclaration
-        app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc));
+        const swaggerUiOptions = await buildSwaggerUiOptions();
+        app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc, swaggerUiOptions));
       }
 
       // Security and CORS

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

@@ -10,6 +10,7 @@ import fs from 'fs-extra';
 import { shellExec } from './process.js';
 import { loggerFactory } from './logger.js';
 import { JSONweb } from './client-formatted.js';
+import { ssrFactory } from './ssr.js';
 
 /**
  * Builds API documentation using Swagger
@@ -62,53 +63,91 @@ const buildApiDocs = async ({
     components: {
       schemas: {
         userRequest: {
-          username: 'user123',
-          password: 'Password123',
-          email: 'user@example.com',
+          type: 'object',
+          required: ['username', 'password', 'email'],
+          properties: {
+            username: { type: 'string', example: 'user123' },
+            password: { type: 'string', example: 'Password123!' },
+            email: { type: 'string', format: 'email', example: 'user@example.com' },
+          },
         },
         userResponse: {
-          status: 'success',
-          data: {
-            token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6IjY2YzM3N2Y1N2Y5OWU1OTY5YjgxZG...',
-            user: {
-              _id: '66c377f57f99e5969b81de89',
-              email: 'user@example.com',
-              emailConfirmed: false,
-              username: 'user123',
-              role: 'user',
-              profileImageId: '66c377f57f99e5969b81de87',
+          type: 'object',
+          properties: {
+            status: { type: 'string', example: 'success' },
+            data: {
+              type: 'object',
+              properties: {
+                token: {
+                  type: 'string',
+                  example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7Il9pZCI6IjY2YzM3N2Y1N2Y5OWU1OTY5YjgxZG...',
+                },
+                user: {
+                  type: 'object',
+                  properties: {
+                    _id: { type: 'string', example: '66c377f57f99e5969b81de89' },
+                    email: { type: 'string', format: 'email', example: 'user@example.com' },
+                    emailConfirmed: { type: 'boolean', example: false },
+                    username: { type: 'string', example: 'user123' },
+                    role: { type: 'string', example: 'user' },
+                    profileImageId: { type: 'string', example: '66c377f57f99e5969b81de87' },
+                  },
+                },
+              },
             },
           },
         },
         userUpdateResponse: {
-          status: 'success',
-          data: {
-            _id: '66c377f57f99e5969b81de89',
-            email: 'user@example.com',
-            emailConfirmed: false,
-            username: 'user123222',
-            role: 'user',
-            profileImageId: '66c377f57f99e5969b81de87',
+          type: 'object',
+          properties: {
+            status: { type: 'string', example: 'success' },
+            data: {
+              type: 'object',
+              properties: {
+                _id: { type: 'string', example: '66c377f57f99e5969b81de89' },
+                email: { type: 'string', format: 'email', example: 'user@example.com' },
+                emailConfirmed: { type: 'boolean', example: false },
+                username: { type: 'string', example: 'user123222' },
+                role: { type: 'string', example: 'user' },
+                profileImageId: { type: 'string', example: '66c377f57f99e5969b81de87' },
+              },
+            },
           },
         },
         userGetResponse: {
-          status: 'success',
-          data: {
-            _id: '66c377f57f99e5969b81de89',
-            email: 'user@example.com',
-            emailConfirmed: false,
-            username: 'user123222',
-            role: 'user',
-            profileImageId: '66c377f57f99e5969b81de87',
+          type: 'object',
+          properties: {
+            status: { type: 'string', example: 'success' },
+            data: {
+              type: 'object',
+              properties: {
+                _id: { type: 'string', example: '66c377f57f99e5969b81de89' },
+                email: { type: 'string', format: 'email', example: 'user@example.com' },
+                emailConfirmed: { type: 'boolean', example: false },
+                username: { type: 'string', example: 'user123222' },
+                role: { type: 'string', example: 'user' },
+                profileImageId: { type: 'string', example: '66c377f57f99e5969b81de87' },
+              },
+            },
           },
         },
         userLogInRequest: {
-          email: 'user@example.com',
-          password: 'Password123',
+          type: 'object',
+          required: ['email', 'password'],
+          properties: {
+            email: { type: 'string', format: 'email', example: 'user@example.com' },
+            password: { type: 'string', example: 'Password123!' },
+          },
         },
         userBadRequestResponse: {
-          status: 'error',
-          message: 'Bad request. Please check your inputs, and try again',
+          type: 'object',
+          properties: {
+            status: { type: 'string', example: 'error' },
+            message: {
+              type: 'string',
+              example: 'Bad request. Please check your inputs, and try again',
+            },
+          },
         },
       },
       securitySchemes: {
@@ -120,6 +159,44 @@ const buildApiDocs = async ({
     },
   };
 
+  /**
+   * swagger-autogen has no requestBody annotation support — it only handles
+   * #swagger.parameters, responses, security, etc.  We define the requestBody
+   * objects here and inject them into the generated JSON as a post-processing step.
+   *
+   * Each key is an "<method> <path>" pair matching the generated paths object.
+   * The value is a valid OAS 3.0 requestBody object.
+   */
+  const requestBodies = {
+    'post /user': {
+      description: 'User registration data',
+      required: true,
+      content: {
+        'application/json': {
+          schema: { $ref: '#/components/schemas/userRequest' },
+        },
+      },
+    },
+    'post /user/auth': {
+      description: 'User login credentials',
+      required: true,
+      content: {
+        'application/json': {
+          schema: { $ref: '#/components/schemas/userLogInRequest' },
+        },
+      },
+    },
+    'put /user/{id}': {
+      description: 'User fields to update',
+      required: true,
+      content: {
+        'application/json': {
+          schema: { $ref: '#/components/schemas/userRequest' },
+        },
+      },
+    },
+  };
+
   logger.warn('build swagger api docs', doc.info);
 
   // swagger-autogen@2.9.2 bug: getProducesTag, getConsumesTag, getResponsesTag missing __¬¬¬__ decode before eval
@@ -148,6 +225,33 @@ const buildApiDocs = async ({
     }
 
     await swaggerAutoGen({ openapi: '3.0.0' })(outputFile, routes, doc);
+
+    // Post-process: inject requestBody into operations — swagger-autogen silently
+    // ignores #swagger.requestBody annotations and has no internal OAS-3 body support.
+    if (fs.existsSync(outputFile)) {
+      const swaggerJson = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+      let patched = false;
+
+      for (const [key, requestBody] of Object.entries(requestBodies)) {
+        const [method, ...pathParts] = key.split(' ');
+        const opPath = pathParts.join(' ');
+        if (swaggerJson.paths?.[opPath]?.[method]) {
+          swaggerJson.paths[opPath][method].requestBody = requestBody;
+          // Remove any stale in:body entry from parameters (OAS 3.0 doesn't allow it)
+          if (Array.isArray(swaggerJson.paths[opPath][method].parameters)) {
+            swaggerJson.paths[opPath][method].parameters = swaggerJson.paths[opPath][method].parameters.filter(
+              (p) => p.in !== 'body',
+            );
+          }
+          patched = true;
+        }
+      }
+
+      if (patched) {
+        fs.writeFileSync(outputFile, JSON.stringify(swaggerJson, null, 2), 'utf8');
+        // logger.warn('swagger post-process: requestBody injected', Object.keys(requestBodies));
+      }
+    }
   });
 };
 
@@ -247,4 +351,18 @@ const buildDocs = async ({
   });
 };
 
-export { buildDocs };
+/**
+ * Builds Swagger UI customization options by rendering the SwaggerDarkMode SSR body component.
+ * Returns the customCss and customJsStr strings required by swagger-ui-express to enable
+ * a dark/light mode toggle button with a black/gray gradient dark theme.
+ * @function buildSwaggerUiOptions
+ * @memberof clientBuildDocs
+ * @returns {Promise<{customCss: string, customJsStr: string}>} Swagger UI setup options
+ */
+const buildSwaggerUiOptions = async () => {
+  const swaggerDarkMode = await ssrFactory('./src/client/ssr/body/SwaggerDarkMode.js');
+  const { css, js } = swaggerDarkMode();
+  return { customCss: css, customJsStr: js };
+};
+
+export { buildDocs, buildSwaggerUiOptions };