underpost 3.2.10 → 3.2.11

package/.vscode/extensions.json

@@ -1,10 +1,10 @@
 {
-    "recommendations": [
-        "anseki.vscode-color",
-        "bashmish.es6-string-css",
-        "eamodio.gitlens",
-        "esbenp.prettier-vscode",
-        "github.copilot-chat",
-        "tobermory.es6-string-html"
-    ]
-}
+  "recommendations": [
+    "anseki.vscode-color",
+    "bashmish.es6-string-css",
+    "eamodio.gitlens",
+    "esbenp.prettier-vscode",
+    "shakram02.bash-beautify",
+    "tobermory.es6-string-html"
+  ]
+}

package/.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "editor.formatOnSave": true,
+  "files.autoSave": "onFocusChange",
   "[javascript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
@@ -11,5 +12,15 @@
   },
   "[typescriptreact]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[shellscript]": {
+    "editor.defaultFormatter": "shakram02.bash-beautify",
+    "editor.formatOnSave": true
+  },
+  "[json]": {
+    "editor.quickSuggestions": {
+      "strings": true
+    },
+    "editor.suggest.insertMode": "replace"
   }
-}
+}

package/CHANGELOG.md

@@ -1,6 +1,79 @@
 # Changelog
 
-## 2026-05-26
+## 2026-05-31
+
+### deploy
+
+- Fix deployment error handling: ensure global secret cleanup only occurs if container status is not 'error' ([83ef9d8cf](https://github.com/underpostnet/engine/commit/83ef9d8cf893c8fe8c07d445b324dd864d9ad842))
+- Add Underpost integration for container status error handling in database and Valkey services ([3bbcdcf49](https://github.com/underpostnet/engine/commit/3bbcdcf49ac6445c6ea5b37d84a5ebc69102a34e))
+
+### bin-build
+
+- Prevent OnError workflow break on empty commit ([494fc93ab](https://github.com/underpostnet/engine/commit/494fc93ab9980d972e66096af5371f5a11173fb4))
+
+### cli-run
+
+- Add k3s-template-env case logic: clean up existing dd-default config and update .env.example ([90a910630](https://github.com/underpostnet/engine/commit/90a910630072fbe3143d87a9aa5a3e479a3ba6e8))
+- Add 'remove' option for resource teardown and improve MongoDB handling ([11c09deb6](https://github.com/underpostnet/engine/commit/11c09deb605138e344cbd30dad3ba446ec950345))
+- Enhance clean method: execute shared-dir script in development mode ([317806d8f](https://github.com/underpostnet/engine/commit/317806d8f9681cb768bd7a1cad87f0c86781fd23))
+- Rename setup-shared-dir method to shared-dir and remove reload-shared-dir method for clarity and simplification ([7985353cb](https://github.com/underpostnet/engine/commit/7985353cb46e5e01e0657c9abb419ddcc6691697))
+- Add exit process on error instead of returning null ([567008c3d](https://github.com/underpostnet/engine/commit/567008c3df4d53ebdab442b44726b323801ec5d3))
+
+### client-core
+
+- Add modal event handling: introduce ModalEventType, ModalListenerChannels, and createModalEvents for improved modal interactions ([d31bf3b01](https://github.com/underpostnet/engine/commit/d31bf3b0171d94f3c0d2496b19bb7001192dc1ac))
+- Fix focus handling in Auth and Modal components: prevent focus on search box when skipFocus is true ([95a42637c](https://github.com/underpostnet/engine/commit/95a42637c6bf7d3f3dd4643663f487321097c218))
+
+### bin-deploy
+
+- Add vm-cluster-env case logic ([d55b6120d](https://github.com/underpostnet/engine/commit/d55b6120d18485865a22745083743091177806b6))
+
+### release
+
+- Refactor release build process: replace file.js with build.template.js, update package.json script, and enhance repository methods for GitHub directory fetching ([05c0e1d85](https://github.com/underpostnet/engine/commit/05c0e1d85bb777b4bc071d4312ed8e6ae6dece51))
+
+### baremetal
+
+- Refactor NFS configuration: update NFSv3 ports and streamline NFS root mount options ([217c736ea](https://github.com/underpostnet/engine/commit/217c736eac25cf68d11b4f9991fc79f0e28a2639))
+- Enhance iPXE build process: track embedded script changes to ensure rebuilds when necessary ([4d9d572bf](https://github.com/underpostnet/engine/commit/4d9d572bfcfff40d0977249e96b34a474cfe582c))
+- Refactor NFS configuration and enhance GRUB module installation for baremetal provisioning ([c94dd434b](https://github.com/underpostnet/engine/commit/c94dd434bbe8792d7694744b7eb57a88256a3415))
+
+### lxd
+
+- Enhance LXD management: add support for MAAS project handling and improve command execution consistency ([0910817c5](https://github.com/underpostnet/engine/commit/0910817c55a4971860d7b363455efd1d1c13d830))
+- Refactor: reorganize LXD Management documentation for clarity and safety ([5cc554cfe](https://github.com/underpostnet/engine/commit/5cc554cfe308f28ee94c7ee3cb141ec6dd156368))
+
+### cluster
+
+- Refactor deployment and monitoring to centralize /etc/hosts management ([a10ad7da6](https://github.com/underpostnet/engine/commit/a10ad7da651085a45c0301489ccb19c92abd2ee7))
+- Add MongoDB manifests including headless service, stateful set, and storage class ([8fd1d8172](https://github.com/underpostnet/engine/commit/8fd1d817250cbebbe2812be9f382d0fc526800ee))
+
+### repository
+
+- Enhance git command execution in file storage and repository modules for improved error handling and logging ([bb008852d](https://github.com/underpostnet/engine/commit/bb008852d9b6b3c9604815a2b0e1d43aba57cc16))
+
+### engine
+
+- Update VSCode configuration: add bash-beautify extension and enhance settings for shellscript and json ([e0e3c5249](https://github.com/underpostnet/engine/commit/e0e3c524923dfcc1c73da2063a4fe7a90ed805d7))
+
+### db
+
+- Refactor MongoDB data directory cleanup logic in Kind nodes to use docker exec for reliability ([87d66f223](https://github.com/underpostnet/engine/commit/87d66f223093695b92f51ce42186e09c06109a45))
+- Refactor MongoDB cleanup logic to avoid stale bind mounts and ensure proper directory structure ([c07098e8c](https://github.com/underpostnet/engine/commit/c07098e8ce9762e3116d8705c1b7206d7ec0df6c))
+
+### cli-secrets
+
+- Add secret management command to deployment workflows ([796fddb46](https://github.com/underpostnet/engine/commit/796fddb46c3c43399de4264ed940f453fd2056e3))
+
+### cli-deploy
+
+- Fix ready monitor method to wait container runtime complete setup ([c89231a06](https://github.com/underpostnet/engine/commit/c89231a06aa5e1ce6decd6550ea5a7f9cf90dd45))
+
+### github-actions
+
+- Prevent dependabot gitleaks run ([16c2a0c1d](https://github.com/underpostnet/engine/commit/16c2a0c1d60ec8d5389288464af60b4a0fcea72d))
+
+## New release v:3.2.10 (2026-05-26)
 
 ### cli-run
 

package/CLI-HELP.md

@@ -1,4 +1,4 @@
-## underpost ci/cd cli v3.2.10
+## underpost ci/cd cli v3.2.11
 
 ### Usage: `underpost [options] [command]`
   ```
@@ -32,7 +32,7 @@ Commands:
   monitor [options] <deploy-id> [env]                        Manages health server monitoring for specified deployments.
   ssh [options]                                              Manages SSH credentials and sessions for remote access to cluster nodes or services.
   run [options] <runner-id> [path]                           Runs specified scripts using various runners.
-  lxd [options]                                              Manages LXD virtual machines as K3s nodes (control plane or workers).
+  lxd [options] [vm-id]                                      Manages LXD virtual machines as K3s nodes (control plane or workers).
   baremetal [options] [workflow-id]                          Manages baremetal server operations, including installation, database setup, commissioning, and user management.
   release [options] [version]                                Release orchestrator for building new versions and deploying releases of the Underpost CLI.
   help [command]                                             display help for command
@@ -422,7 +422,8 @@ Options:
                                        statefulset.
   --mongodb                            Initializes the cluster with a MongoDB
                                        statefulset.
-  --mongo-db-host <host>               Set custom mongo db host
+  --service-host <host>                Set custom host/IP for exposed MongoDB
+                                       and Valkey clients.
   --postgresql                         Initializes the cluster with a PostgreSQL
                                        statefulset.
   --mongodb4                           Initializes the cluster with a MongoDB
@@ -433,6 +434,14 @@ Options:
                                        ipfs-cluster statefulset.
   --contour                            Initializes the cluster with Project
                                        Contour base HTTPProxy and Envoy.
+  --node-port                          Exposes enabled ready services (e.g.
+                                       MongoDB 4.4, Valkey) to the host/public
+                                       network via their NodePort Service
+                                       manifest.
+  --node-selector <k8s-node-name>      Pins the just-deployed StatefulSet
+                                       (MongoDB 4.4 / Valkey) to the given
+                                       Kubernetes node once it is ready (via a
+                                       kubernetes.io/hostname nodeSelector).
   --cert-manager                       Initializes the cluster with a Let's
                                        Encrypt production ClusterIssuer.
   --dedicated-gpu                      Initializes the cluster with dedicated
@@ -475,6 +484,10 @@ Options:
                                        hostnames or IP addresses.
   --remove-volume-host-paths           Removes specified volume host paths after
                                        execution.
+  --reset-mode <mode>                  Reset mode for --reset --k3s: "drain"
+                                       (stop services, keep K3s installed) or
+                                       "full" (uninstall + cleanup). Default:
+                                       "full".
   --namespace <namespace>              Kubernetes namespace for cluster
                                        operations (defaults to "default").
   --replicas <replicas>                Sets a custom number of replicas for
@@ -546,9 +559,6 @@ Options:
                                       operations.
   --git-clean                         Runs git clean on volume mount paths
                                       before copying.
-  --etc-hosts                         Enables the etc-hosts context for
-                                      deployment operations.
-  --restore-hosts                     Restores default `/etc/hosts` entries.
   --disable-update-underpost-config   Disables updates to Underpost
                                       configuration during deployment.
   --namespace <namespace>             Kubernetes namespace for deployment
@@ -912,7 +922,7 @@ Options:
 Runs specified scripts using various runners.
 
 Arguments:
-  runner-id                                       The runner ID to run. Options: dev-cluster,ipfs-expose,metadata,svc-ls,svc-rm,ssh-deploy-info,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,sh,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,pull-rocky-image,rmi,kill,generate-pass,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,setup-shared-dir,reload-shared-dir.
+  runner-id                                       The runner ID to run. Options: dev-cluster,ipfs-expose,metadata,svc-ls,svc-rm,ssh-deploy-info,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,sh,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,pull-rocky-image,rmi,kill,generate-pass,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,monitor-ui,shared-dir.
   path                                            The input value, identifier, or path for the operation.
 
 Options:
@@ -982,6 +992,7 @@ Options:
   --copy                                          Copies the runner output to the clipboard (supported by: generate-pass, template-deploy-local).
   --skip-full-build                               Skip client bundle rebuild; triggers pull-bundle in container startup (supported by: sync, template-deploy).
   --pull-bundle                                   Explicitly download the pre-built client bundle from Cloudinary inside the container (supported by: sync, template-deploy). Use together with --skip-full-build.
+  --remove                                        Remove/teardown resources
   -h, --help                                      display help for command
  
 ```
@@ -989,16 +1000,36 @@ Options:
 
 ### `lxd` :
 ```
- Usage: underpost lxd [options]
+ Usage: underpost lxd [options] [vm-id]
 
 Manages LXD virtual machines as K3s nodes (control plane or workers).
 
+Arguments:
+  vm-id                            VM identifier shared by current-VM flags like
+                                   --vm-create, --vm-delete, --vm-init,
+                                   --vm-info, and --vm-test.
+
 Options:
   --init                           Initializes LXD on the current machine via
                                    preseed.
-  --reset                          SAFE complete reset: cleans all VMs (proxy
-                                   devices first), profiles, networks, then
-                                   removes LXD snap.
+  --reset                          Host-safe reset: removes proxy devices,
+                                   stops/deletes VMs, drops admin-profile and
+                                   lxdbr0. Does NOT touch the LXD snap or
+                                   storage pools.
+  --purge                          DESTRUCTIVE: gracefully shuts down the LXD
+                                   daemon (60s timeout), then removes the LXD
+                                   snap. Combine with --reset to wipe per-VM
+                                   state first. Safe replacement for the prior
+                                   aggressive teardown.
+  --shutdown                       Pre-host-reboot procedure: gracefully stops
+                                   every VM and the LXD daemon. Run BEFORE any
+                                   reboot/poweroff to keep the host bootable.
+  --restore                        Symmetric to --shutdown: starts the LXD
+                                   daemon, waits for it to be responsive, then
+                                   starts every VM. VMs created via
+                                   admin-profile have boot.autostart=false, so
+                                   this is the explicit "bring the lab back up"
+                                   command.
   --install                        Installs the LXD snap.
   --dev                            Use local paths instead of the global npm
                                    installation.
@@ -1010,31 +1041,54 @@ Options:
                                    plane node.
   --worker                         Initialize the target VM as a K3s worker
                                    node.
-  --create-vm <vm-name>            Copy the LXC launch command for a new K3s VM
-                                   to the clipboard.
-  --delete-vm <vm-name>            SAFELY stop and delete VM (removes proxy
-                                   devices first, then stops, then deletes).
-                                   Safe to re-run.
-  --init-vm <vm-name>              Run k3s-node-setup.sh on the specified VM
-                                   (use with --control or --worker).
-  --info-vm <vm-name>              Display full configuration and status for the
-                                   specified VM.
-  --test <vm-name>                 Run connectivity and health checks on the
-                                   specified VM.
-  --root-size <gb-size>            Root disk size in GiB for --create-vm
+  --vm-create                      Copy the LXC launch command for the command
+                                   argument [vm-id] to the clipboard.
+  --vm-delete                      SAFELY stop and delete the command argument
+                                   [vm-id] (removes proxy devices first, then
+                                   stops, then deletes). Safe to re-run.
+  --vm-init                        Bring the command argument [vm-id] up as a
+                                   K3s node end-to-end: OS base setup, mirror
+                                   /home/dd/engine into the VM, then K3s role
+                                   install via the local engine (use with
+                                   --control or --worker).
+  --vm-info                        Display full configuration and status for the
+                                   command argument [vm-id].
+  --vm-test                        Run connectivity and health checks on the
+                                   command argument [vm-id].
+  --vm-sync-engine                 Re-copy the host engine source into the
+                                   command argument [vm-id], overriding whatever
+                                   is currently there (equivalent to the
+                                   engine-bootstrap step of --vm-init in
+                                   isolation).
+  --root-size <gb-size>            Root disk size in GiB for --vm-create
                                    (default: 32).
   --join-node <nodes>              Join a K3s worker to a control plane.
                                    Standalone format: "workerName,controlName".
-                                   When used with --init-vm --worker, provide
+                                   When used with --vm-init --worker, provide
                                    just the control node name for auto-join.
   --expose <vm-name:ports>         Proxy host ports to a VM (e.g.,
                                    "k3s-control:80,443").
+  --node-port <port>               Customizes the VM-side (connect) port for
+                                   --expose, so the host listens on the given
+                                   port but proxies to this NodePort inside the
+                                   VM (e.g. expose host 27017 -> VM NodePort
+                                   32017).
   --delete-expose <vm-name:ports>  Remove proxied ports from a VM (e.g.,
                                    "k3s-control:80,443").
-  --bootstrap-engine <vm-name>     Replicate /home/dd/engine source into the VM
-                                   after init completes.
+  --copy                           For two-phase flows that surface a command
+                                   for the user to execute (e.g.
+                                   --create-admin-profile phase 1), copy the
+                                   command to the clipboard instead of printing
+                                   it to the terminal.
   --namespace <namespace>          Kubernetes namespace context (defaults to
                                    "default").
+  --maas-project <project>         LXD project managed by MAAS (e.g.
+                                   "k3s-cluster"). When set, all lxc commands
+                                   target this project so MAAS enumerates the
+                                   VMs in its machines UI.
+  --move-to-project                Stop the [vm-id] VM in the default project,
+                                   move it to --maas-project, then start it so
+                                   MAAS picks it up. Requires --maas-project.
   -h, --help                       display help for 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.ci.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) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.10)](https://socket.dev/npm/package/underpost/overview/3.2.10) [![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.ci.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) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.11)](https://socket.dev/npm/package/underpost/overview/3.2.11) [![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>
 
@@ -90,7 +90,7 @@ npm run dev
 <a target="_top" href="https://www.nexodev.org/docs?cid=src">See Docs.</a>
 
 <!-- cli-index-start -->
-## underpost ci/cd cli v3.2.10
+## underpost ci/cd cli v3.2.11
 
 ### Usage: `underpost [options] [command]`
   ```
@@ -124,7 +124,7 @@ Commands:
   monitor [options] <deploy-id> [env]                        Manages health server monitoring for specified deployments.
   ssh [options]                                              Manages SSH credentials and sessions for remote access to cluster nodes or services.
   run [options] <runner-id> [path]                           Runs specified scripts using various runners.
-  lxd [options]                                              Manages LXD virtual machines as K3s nodes (control plane or workers).
+  lxd [options] [vm-id]                                      Manages LXD virtual machines as K3s nodes (control plane or workers).
   baremetal [options] [workflow-id]                          Manages baremetal server operations, including installation, database setup, commissioning, and user management.
   release [options] [version]                                Release orchestrator for building new versions and deploying releases of the Underpost CLI.
   help [command]                                             display help for command

package/bin/build.js

@@ -64,11 +64,12 @@ if (process.argv.includes('conf')) {
     }
     shellExec(
       `cd ../${privateRepoName}` +
-      ` && git add .` +
-      ` && underpost cmt . ci engine-core-conf 'Update ${_confName} conf'` +
-      ` && underpost push . ${privateGitUri}`,
+        ` && git add .` +
+        ` && underpost cmt . ci engine-core-conf 'Update ${_confName} conf'` +
+        ` && underpost push . ${privateGitUri}`,
       {
         silent: true,
+        silentOnError: true,
       },
     );
   }
@@ -163,11 +164,13 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         `./.github/workflows/publish.cyberia.ci.yml`,
         `${basePath}/.github/workflows/publish.cyberia.ci.yml`,
       );
-      delete packageJson.bin.underpost;
+      if (packageJson.bin) delete packageJson.bin.underpost;
+      if (!packageJson.bin) packageJson.bin = {};
       packageJson.bin.cyberia = 'bin/index.js';
       packageJson.keywords = [
         'cyberia',
         'cyberia-cli',
+        'engine-cyberia',
         'sidecar',
         'data-layer',
         'engine-cyberia',
@@ -181,7 +184,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         'blockchain',
         'web3',
         'underpost-platform',
-        'mmo-extension',
+        'mmorpg',
       ];
       packageJson.description =
         'Cyberia CLI — toolchain for the Cyberia MMO data layer, content pipeline, persistence, gRPC services, and ERC-1155 lifecycle on Hyperledger Besu.';
@@ -213,7 +216,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         '/src/runtime/cyberia-client',
         '/.github/workflows/hardhat.ci.yml',
         '/src/client/public/cyberia-docs',
-        '/src/api/cyberia-server-defaults'
+        '/src/api/cyberia-server-defaults',
       ])
         fs.copySync(`.${path}`, `${basePath}${path}`);
 

package/bin/build.template.js

@@ -0,0 +1,187 @@
+import fs from 'fs-extra';
+
+import { loggerFactory } from '../src/server/logger.js';
+import { getDirname, newInstance, uniqueArray } from '../src/client/components/core/CommonJs.js';
+import { shellExec } from '../src/server/process.js';
+import walk from 'ignore-walk';
+import { validateTemplatePath } from '../src/server/conf.js';
+import dotenv from 'dotenv';
+
+const logger = loggerFactory(import.meta);
+
+if (fs.existsSync('./engine-private/conf/dd-cron/.env.production'))
+  dotenv.config({
+    path: `./engine-private/conf/dd-cron/.env.production`,
+    override: true,
+  });
+else dotenv.config();
+
+// Engine-only paths stripped from the template after the source sync.
+const TEMPLATE_DELETE_PATHS = [
+  './.github',
+  './manifests/deployment/dd-lampp-development',
+  './manifests/deployment/dd-cyberia-development',
+  './manifests/deployment/dd-core-development',
+  './manifests/deployment/dd-template-development',
+  './src/server/object-layer.js',
+  './src/server/atlas-sprite-sheet-generator.js',
+  './src/server/shape-generator.js',
+  './src/server/semantic-layer-generator.js',
+  './src/server/semantic-layer-generator-floor.js',
+  './src/server/semantic-layer-generator-skin.js',
+  './src/server/semantic-layer-generator-resource.js',
+  './src/server/besu-genesis-generator.js',
+  './src/grpc/cyberia',
+  './src/runtime/cyberia-server',
+  './src/runtime/cyberia-client',
+  './test/shape-generator.test.js',
+  './src/client/public/cyberia-docs',
+  'bin/cyberia.js',
+  './hardhat',
+];
+
+// Workflow + service files re-added to the template after the engine-only strip above.
+const TEMPLATE_RESTORE_PATHS = [
+  `./.github/workflows/pwa-microservices-template-page.cd.yml`,
+  `./.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/client/services/user/guest.service.js`,
+  './src/api/user/guest.service.js',
+  './src/ws/IoInterface.js',
+  './src/ws/IoServer.js',
+];
+
+const TEMPLATE_KEYWORDS = [
+  'underpost',
+  'underpost-platform',
+  'cli',
+  'toolchain',
+  'ci-cd',
+  'devops',
+  'kubernetes',
+  'k3s',
+  'kubeadm',
+  'lxd',
+  'bare-metal',
+  'container-orchestration',
+  'image-management',
+  'pwa',
+  'workbox',
+  'microservices',
+];
+
+const TEMPLATE_DESCRIPTION =
+  'Underpost Platform — end-to-end CI/CD and application-delivery toolchain CLI. Covers bare metal, Kubernetes, K3s, kubeadm, LXD, container/image orchestration, secrets, databases, cron jobs, monitoring, SSH, runners, PWA + Workbox delivery, and release orchestration. Extensible via downstream CLIs.';
+
+/**
+ * Builds the pwa-microservices-template from scratch out of the current engine source tree.
+ *
+ * Clones (or resets) the template repo next to the engine, syncs every engine-tracked file the
+ * template is allowed to carry (validateTemplatePath), strips engine-only modules, restores the
+ * template's own CI workflows + guest services, and rewrites package.json / package-lock.json /
+ * README so the template is a standalone, installable project.
+ *
+ * Usage: node bin/build.template [srcPath=./] [toPath=../pwa-microservices-template]
+ */
+const srcPath = (process.argv[2] ?? './').replaceAll(`'`, '');
+const toPath = (process.argv[3] ?? '../pwa-microservices-template').replaceAll(`'`, '');
+const githubUsername = process.env.GITHUB_USERNAME;
+
+logger.info('Build template', { srcPath, toPath });
+
+try {
+  const sourceFiles = (
+    await new Promise((resolve) =>
+      walk(
+        {
+          path: srcPath,
+          ignoreFiles: [`.gitignore`],
+          includeEmpty: false,
+          follow: false,
+        },
+        (...args) => resolve(args[1]),
+      ),
+    )
+  ).filter((p) => !p.startsWith('.git'));
+
+  // Clone the template from 0 if missing; otherwise reset it to a clean pristine checkout.
+  if (!fs.existsSync(toPath)) {
+    shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
+  } else {
+    shellExec(`cd ${toPath} && git reset && git checkout . && git clean -f -d`);
+    shellExec(`node bin pull ${toPath} ${githubUsername}/pwa-microservices-template`);
+    shellExec(`sudo rm -rf ${toPath}/engine-private`);
+    shellExec(`sudo rm -rf ${toPath}/logs`);
+  }
+  shellExec(`cd ${toPath} && git config core.filemode false`);
+
+  for (const copyPath of sourceFiles) {
+    if (copyPath === 'NaN') continue;
+    const absolutePath = `${srcPath}/${copyPath}`;
+    if (!validateTemplatePath(absolutePath)) continue;
+
+    const folder = getDirname(`${toPath}/${copyPath}`);
+    if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+
+    logger.info('build', `${toPath}/${copyPath}`);
+    fs.copyFileSync(absolutePath, `${toPath}/${copyPath}`);
+  }
+
+  fs.copySync(`./.vscode`, `${toPath}/.vscode`);
+  fs.copySync(`./src/client/public/default`, `${toPath}/src/client/public/default`);
+
+  // Preserve the template's own README + package.json identity before merging engine metadata.
+  for (const checkoutPath of ['README.md', 'package.json']) shellExec(`cd ${toPath} && git checkout ${checkoutPath}`);
+
+  for (const deletePath of TEMPLATE_DELETE_PATHS) {
+    const target = `${toPath}/${deletePath}`;
+    if (fs.existsSync(target)) fs.removeSync(target);
+  }
+
+  fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
+  for (const restorePath of TEMPLATE_RESTORE_PATHS) fs.copyFileSync(restorePath, `${toPath}/${restorePath}`);
+
+  // ── package.json: take engine deps/scripts/version, keep template identity. ──
+  const originPackageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+  const templatePackageJson = JSON.parse(fs.readFileSync(`${toPath}/package.json`, 'utf8'));
+  const templateName = templatePackageJson.name;
+
+  templatePackageJson.dependencies = originPackageJson.dependencies;
+  templatePackageJson.devDependencies = originPackageJson.devDependencies;
+  templatePackageJson.version = originPackageJson.version;
+  templatePackageJson.scripts = originPackageJson.scripts;
+  templatePackageJson.overrides = originPackageJson.overrides;
+  templatePackageJson.name = templateName;
+  templatePackageJson.description = TEMPLATE_DESCRIPTION;
+  templatePackageJson.keywords = uniqueArray(TEMPLATE_KEYWORDS.concat(templatePackageJson.keywords || []));
+  delete templatePackageJson.scripts['update:template'];
+  fs.writeFileSync(`${toPath}/package.json`, JSON.stringify(templatePackageJson, null, 4), 'utf8');
+
+  // ── package-lock.json: mirror engine packages, keep template name/version on the root entry. ──
+  const originPackageLockJson = JSON.parse(fs.readFileSync('./package-lock.json', 'utf8'));
+  const templatePackageLockJson = JSON.parse(fs.readFileSync(`${toPath}/package-lock.json`, 'utf8'));
+  const originBasePackageLock = newInstance(templatePackageLockJson.packages['']);
+  templatePackageLockJson.name = templateName;
+  templatePackageLockJson.version = originPackageLockJson.version;
+  templatePackageLockJson.packages = originPackageLockJson.packages;
+  templatePackageLockJson.packages[''].name = templateName;
+  templatePackageLockJson.packages[''].version = originPackageLockJson.version;
+  templatePackageLockJson.packages[''].hasInstallScript = originBasePackageLock.hasInstallScript;
+  templatePackageLockJson.packages[''].license = originBasePackageLock.license;
+  fs.writeFileSync(`${toPath}/package-lock.json`, JSON.stringify(templatePackageLockJson, null, 4), 'utf8');
+
+  fs.writeFileSync(
+    `${toPath}/README.md`,
+    fs
+      .readFileSync('./README.md', 'utf8')
+      .replace('<!-- template-title -->', '#### Base template for pwa/api-rest projects.'),
+    'utf8',
+  );
+} catch (error) {
+  logger.error(error, error.stack);
+  process.exit(1);
+}