underpost 3.2.8 → 3.2.10

package/src/cli/run.js

@@ -24,6 +24,7 @@ import { range, setPad, timer } from '../client/components/core/CommonJs.js';
 import os from 'os';
 import Underpost from '../index.js';
 import dotenv from 'dotenv';
+import { MongoBootstrap } from '../db/mongo/MongoBootstrap.js';
 
 const waitForPort = (port, host = '127.0.0.1', { maxAttempts = 30, interval = 2000 } = {}) =>
   new Promise((resolve, reject) => {
@@ -97,6 +98,7 @@ const logger = loggerFactory(import.meta);
  * @property {string} deployId - The deployment ID.
  * @property {string} instanceId - The instance ID.
  * @property {string} user - The user to run as.
+ * @property {string} group - The group to use.
  * @property {string} pid - The process ID.
  * @property {boolean} disablePrivateConfUpdate - Whether to disable private configuration updates.
  * @property {string} monitorStatus - The monitor status option.
@@ -110,6 +112,10 @@ const logger = loggerFactory(import.meta);
  * @property {string|Array<{ip: string, hostnames: string[]}>} hostAliases - Adds entries to the Pod /etc/hosts via Kubernetes hostAliases.
  *   As a string (CLI): semicolon-separated entries of "ip=hostname1,hostname2" (e.g., "127.0.0.1=foo.local,bar.local;10.1.2.3=foo.remote").
  *   As an array (programmatic): objects with `ip` and `hostnames` fields (e.g., [{ ip: "127.0.0.1", hostnames: ["foo.local"] }]).
+ * @property {boolean} gitClean - Whether to perform a `git clean` before running.
+ * @property {boolean} copy - Whether to copy the command to the clipboard instead of executing it.
+ * @property {boolean} skipFullBuild - Whether to skip the full client bundle build during deployment (supported by: sync, template-deploy).
+ * @property {boolean} pullBundle - Whether to pull the bundle before running. Use together with --skip-full-build to skip the local build entirely (supported by: sync, template-deploy).
  * @memberof UnderpostRun
  */
 const DEFAULT_OPTION = {
@@ -161,6 +167,7 @@ const DEFAULT_OPTION = {
   deployId: '',
   instanceId: '',
   user: '',
+  group: '',
   pid: '',
   disablePrivateConfUpdate: false,
   monitorStatus: '',
@@ -174,6 +181,8 @@ const DEFAULT_OPTION = {
   hostAliases: '',
   gitClean: false,
   copy: false,
+  skipFullBuild: false,
+  pullBundle: false,
 };
 
 /**
@@ -219,7 +228,7 @@ class UnderpostRun {
         // Detect MongoDB primary pod using method
         let primaryMongoHost = 'mongodb-0.mongodb-service';
         try {
-          const primaryPodName = Underpost.db.getMongoPrimaryPodName({
+          const primaryPodName = MongoBootstrap.getPrimaryPodName({
             namespace: options.namespace,
             podName: 'mongodb-0',
           });
@@ -435,6 +444,15 @@ class UnderpostRun {
         deployType = 'init';
       }
 
+      // If --build is set and path is a sync-engine-* target, push the pre-built client bundle
+      // to Cloudinary so the remote container can pull it instead of rebuilding from source.
+      if (options.build && deployConfId && deployConfId.startsWith('engine-')) {
+        const confName = deployConfId.replace(/^engine-/, '');
+        const pushDeployId = options.deployId || `dd-${confName}`;
+        logger.info(`[template-deploy] Running push-bundle for deployId: ${pushDeployId}`);
+        shellExec(`${baseCommand} run push-bundle --deploy-id ${pushDeployId}`);
+      }
+
       // Dispatch npmpkg CI workflow — this builds pwa-microservices-template first.
       // If deployConfId is set, npmpkg.ci.yml will dispatch the engine-<conf-id> CI
       // with sync=true after template build completes. The engine CI then dispatches
@@ -490,14 +508,16 @@ class UnderpostRun {
     },
     /**
      * @method docker-image
-     * @description Dispatches the Docker image CI workflow (`docker-image.ci.yml`) for the `engine` repository via `workflow_dispatch`.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @description Dispatches the Docker image CI workflow (`docker-image[.<runtime>].ci.yml`) via `workflow_dispatch`.
+     * Repository resolution is delegated to `Underpost.repo.resolveInstanceRepo(path)`.
+     * @param {string} path - Optional runtime / workflow suffix (e.g. `cyberia-server`, `cyberia-client`).
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'docker-image': (path, options = DEFAULT_OPTION) => {
+      const repo = Underpost.repo.resolveInstanceRepo(path);
       Underpost.repo.dispatchWorkflow({
-        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        repo,
         workflowFile: `docker-image${path ? `.${path}` : ''}.ci.yml`,
         ref: 'master',
         inputs: {},
@@ -521,16 +541,14 @@ class UnderpostRun {
      * @memberof UnderpostRun
      */
     pull: (path, options = DEFAULT_OPTION) => {
+      // shellExec is fail-fast by default — any non-zero exit throws and
+      // propagates up to the workflow step. No per-call flag required.
       if (!fs.existsSync(`/home/dd`) || !fs.existsSync(`/home/dd/engine`)) {
         fs.mkdirSync(`/home/dd`, { recursive: true });
-        shellExec(`cd /home/dd && underpost clone ${process.env.GITHUB_USERNAME}/engine`, {
-          silent: true,
-        });
+        shellExec(`cd /home/dd && underpost clone ${process.env.GITHUB_USERNAME}/engine`, { silent: true });
       } else {
         shellExec(`underpost run clean`);
-        shellExec(`cd /home/dd/engine && underpost pull . ${process.env.GITHUB_USERNAME}/engine`, {
-          silent: true,
-        });
+        shellExec(`cd /home/dd/engine && underpost pull . ${process.env.GITHUB_USERNAME}/engine`, { silent: true });
       }
       if (!fs.existsSync(`/home/dd/engine/engine-private`))
         shellExec(`cd /home/dd/engine && underpost clone ${process.env.GITHUB_USERNAME}/engine-private`, {
@@ -539,9 +557,7 @@ class UnderpostRun {
       else
         shellExec(
           `cd /home/dd/engine/engine-private && underpost pull . ${process.env.GITHUB_USERNAME}/engine-private`,
-          {
-            silent: true,
-          },
+          { silent: true },
         );
     },
     /**
@@ -628,6 +644,11 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
     /**
      * @method sync
      * @description Cleans up, and then runs a deployment synchronization command (`underpost deploy --kubeadm --build-manifest --sync...`) using parameters parsed from `path` (deployId, replicas, versions, image, node).
+     *
+     * Forwards `--image-pull-policy <policy>` to the underlying `deploy --build-manifest` invocation when `options.imagePullPolicy` is set,
+     * which then plumbs through `buildManifest` and `deploymentYamlPartsFactory` to override the container `imagePullPolicy` in the generated
+     * `deployment.yaml`. Useful when you want to force `Always` so the kubelet re-pulls a mutable tag on every rollout. Example:
+     *   `node bin run sync dd-core --kubeadm --image-pull-policy Always`
      * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string containing deploy parameters).
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
@@ -683,12 +704,16 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         : '';
       const gitCleanFlag = options.gitClean ? ' --git-clean' : '';
 
+      const skipFullBuildFlag = options.skipFullBuild ? ' --skip-full-build' : '';
+      const pullBundleFlag = options.pullBundle ? ' --pull-bundle' : '';
+      const imagePullPolicyFlag = options.imagePullPolicy ? ` --image-pull-policy ${options.imagePullPolicy}` : '';
+
       shellExec(
         `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
           image ? ` --image ${image}` : ''
         }${versions ? ` --versions ${versions}` : ''}${
           options.namespace ? ` --namespace ${options.namespace}` : ''
-        }${timeoutFlags}${cmdString}${gitCleanFlag} ${deployId} ${env}`,
+        }${timeoutFlags}${cmdString}${gitCleanFlag}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag} ${deployId} ${env}`,
       );
 
       if (isDeployRunnerContext(path, options)) {
@@ -699,7 +724,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         shellExec(
           `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
             options.namespace ? ` --namespace ${options.namespace}` : ''
-          }${timeoutFlags}${gitCleanFlag}`,
+          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}`,
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
@@ -1005,6 +1030,9 @@ EOF
           cmd: _cmd,
           volumes: _volumes,
           metadata: _metadata,
+          lifecycle: _lifecycle,
+          readinessProbe: _readinessProbe,
+          livenessProbe: _livenessProbe,
         } = instance;
         if (id !== _id) continue;
         const _deployId = `${deployId}-${_id}`;
@@ -1069,6 +1097,20 @@ EOF
           ),
         );
 
+        // Resolve env-scoped lifecycle/probe blocks: each can be either
+        //   { ...envObj }                        // shared shape
+        //   { development: {...}, production: {...} }   // env-specific
+        const pickEnv = (v) => (v && (v.development || v.production) ? v[env] : v);
+
+        // Convention: an instance config may place `imagePullPolicy` inside
+        // the env-scoped lifecycle block (alongside postStart/preStop).
+        // Extract it onto the container spec (where K8S expects it) and
+        // strip it from the lifecycle hash so the rendered YAML stays valid.
+        // CLI override (`--image-pull-policy`) wins over the conf value.
+        const { lifecycle: lifecycleForManifest, imagePullPolicy: lifecycleImagePullPolicy } =
+          Underpost.deploy.extractInstanceImagePullPolicy(pickEnv(_lifecycle));
+        const instanceImagePullPolicy = options.imagePullPolicy || lifecycleImagePullPolicy;
+
         let deploymentYaml = `---
 ${Underpost.deploy
   .deploymentYamlPartsFactory({
@@ -1081,6 +1123,11 @@ ${Underpost.deploy
     namespace: options.namespace,
     volumes: _volumes,
     cmd: resolvedCmd,
+    lifecycle: lifecycleForManifest,
+    readinessProbe: pickEnv(_readinessProbe),
+    livenessProbe: pickEnv(_livenessProbe),
+    containerPort: _toPort,
+    imagePullPolicy: instanceImagePullPolicy,
   })
   .replace('{{ports}}', buildKindPorts(_fromPort, _toPort))}
 `;
@@ -1169,14 +1216,34 @@ EOF
         volumes: _volumes,
         metadata: _metadata,
         runtime: _runtime,
+        lifecycle: _lifecycle,
+        readinessProbe: _readinessProbe,
+        livenessProbe: _livenessProbe,
       } = instance;
 
-      // Resolve Dockerfile source: use runtime-specific path when instance defines a runtime.
-      const dockerfileSourcePath = _runtime ? `src/runtime/${_runtime}/Dockerfile` : `${rootPath}/Dockerfile`;
-      if (fs.existsSync(dockerfileSourcePath)) {
+      // Resolve Dockerfile source. Dev/prod variant rules:
+      //   - When the instance defines a `runtime`, look under
+      //     `src/runtime/<runtime>/`. In `--dev` mode prefer `Dockerfile.dev`
+      //     when it exists, falling back to `Dockerfile`.
+      //   - When `runtime` is not set, look in the project root with the
+      //     same `.dev` → no-suffix precedence.
+      // Dockerfile.dev is a full Dockerfile (not an overlay) — each runtime
+      // owns the contract between its dev image and its prod image (debug
+      // build flags, extra tooling, default ports, etc.).
+      const dockerfileBase = _runtime ? `src/runtime/${_runtime}` : rootPath;
+      const dockerfileCandidates = options.dev
+        ? [`${dockerfileBase}/Dockerfile.dev`, `${dockerfileBase}/Dockerfile`]
+        : [`${dockerfileBase}/Dockerfile`];
+      const dockerfileSourcePath = dockerfileCandidates.find((p) => fs.existsSync(p));
+      if (dockerfileSourcePath) {
+        if (options.dev && !dockerfileSourcePath.endsWith('.dev')) {
+          logger.warn(
+            `[instance-build-manifest] --dev requested but no Dockerfile.dev present; falling back to ${dockerfileSourcePath}`,
+          );
+        }
         fs.copyFileSync(dockerfileSourcePath, dockerfileManifestPath);
       } else {
-        logger.warn(`[instance-build-manifest] Dockerfile not found at ${dockerfileSourcePath}`);
+        logger.warn(`[instance-build-manifest] Dockerfile not found; tried: ${dockerfileCandidates.join(', ')}`);
       }
 
       const _deployId = `${deployId}-${_id}`;
@@ -1221,6 +1288,17 @@ EOF
         ),
       );
 
+      // Env-aware lifecycle / probe selection. Each block may either be
+      // a single object (shared across envs) or `{ development, production }`.
+      const pickEnv = (v) => (v && (v.development || v.production) ? v[env] : v);
+
+      // Convention: an instance config may place `imagePullPolicy` inside
+      // the env-scoped lifecycle block (alongside postStart/preStop).
+      // Extract it onto the container spec and strip it from the lifecycle hash.
+      const { lifecycle: lifecycleForManifest, imagePullPolicy: lifecycleImagePullPolicy } =
+        Underpost.deploy.extractInstanceImagePullPolicy(pickEnv(_lifecycle));
+      const instanceImagePullPolicy = options.imagePullPolicy || lifecycleImagePullPolicy;
+
       const deploymentYaml =
         `---\n` +
         Underpost.deploy
@@ -1234,6 +1312,11 @@ EOF
             namespace: options.namespace,
             volumes: _volumes,
             cmd: resolvedCmd,
+            lifecycle: lifecycleForManifest,
+            readinessProbe: pickEnv(_readinessProbe),
+            livenessProbe: pickEnv(_livenessProbe),
+            containerPort: _toPort,
+            imagePullPolicy: instanceImagePullPolicy,
           })
           .replace('{{ports}}', buildKindPorts(_fromPort, _toPort));
 
@@ -1288,6 +1371,44 @@ EOF
       shellExec(`${options.underpostRoot}/scripts/rocky-setup.sh${options.dev ? ' --install-dev' : ``}`);
     },
 
+    /**
+     * @method install-crio
+     * @description Installs and configures CRI-O as the container runtime for kubeadm clusters.
+     * Adds the stable v1.33 CRI-O yum repository, installs the `cri-o` package, configures
+     * the systemd cgroup driver, enables the `crio` service, and writes `/etc/crictl.yaml`
+     * so that `crictl` targets the CRI-O socket by default.
+     * @param {string} path - Unused.
+     * @param {Object} options - The default underpost runner options for customizing workflow.
+     * @memberof UnderpostRun
+     */
+    'install-crio': (path, options = DEFAULT_OPTION) => {
+      logger.info('Installing CRI-O...');
+      shellExec(`cat <<EOF | sudo tee /etc/yum.repos.d/cri-o.repo
+[cri-o]
+name=CRI-O
+baseurl=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/v1.33/rpm/
+enabled=1
+gpgcheck=1
+gpgkey=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/v1.33/rpm/repodata/repomd.xml.key
+EOF`);
+      shellExec(`sudo dnf -y install cri-o`);
+      // crictl is in the kubernetes repo but excluded by default — install it explicitly
+      shellExec(`sudo yum install -y cri-tools --disableexcludes=kubernetes`);
+      // Ensure CRI-O uses systemd cgroup driver (matches kubelet default)
+      shellExec(`sudo sed -i 's/^#\?cgroup_manager =.*/cgroup_manager = "systemd"/' /etc/crio/crio.conf`, {
+        silentOnError: true,
+      });
+      shellExec(`sudo systemctl enable --now crio`);
+      logger.info('CRI-O installed and started.');
+      // Write crictl config so all crictl calls default to the CRI-O socket
+      shellExec(`cat <<EOF | sudo tee /etc/crictl.yaml
+runtime-endpoint: unix:///var/run/crio/crio.sock
+image-endpoint: unix:///var/run/crio/crio.sock
+timeout: 10
+debug: false
+EOF`);
+    },
+
     /**
      * @method dd-container
      * @description Deploys a development or debug container tasks jobs, setting up necessary volumes and images, and running specified commands within the container.
@@ -1430,6 +1551,9 @@ EOF
     /**
      * @method promote
      * @description Switches traffic between blue/green deployments for a specified deployment ID(s) (uses `dd.router` for 'dd', or a specific ID).
+     * When `--tls` is set, rebuilds the proxy manifest with `--cert` so the HTTPProxy includes
+     * TLS config, deletes stale Certificate resources, then reapplies the proxy and secret.yaml
+     * (cert-manager Certificate resources) for each affected deployment.
      * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string: `deployId,env,replicas`).
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
@@ -1438,11 +1562,34 @@ EOF
       let [inputDeployId, inputEnv, inputReplicas] = path.split(',');
       if (!inputEnv) inputEnv = 'production';
       if (!inputReplicas) inputReplicas = 1;
+      // TODO: normalize: --tls maps to --cert for deploy.js isValidTLSContext compatibility
+      if (options.tls) options.cert = true;
+
+      const applyCerts = (deployId, targetTraffic) => {
+        if (!options.tls) return;
+        // Rebuild proxy.yaml with --cert so the HTTPProxy includes TLS virtualhost config
+        shellExec(
+          `node bin deploy --build-manifest --cert --traffic ${targetTraffic} --replicas ${inputReplicas} --namespace ${options.namespace} ${deployId} ${inputEnv}`,
+        );
+        // Delete stale Certificate resources before reapplying
+        const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+        if (fs.existsSync(confServerPath)) {
+          for (const host of Object.keys(JSON.parse(fs.readFileSync(confServerPath, 'utf8'))))
+            shellExec(`sudo kubectl delete Certificate ${host} -n ${options.namespace} --ignore-not-found`);
+        }
+        shellExec(
+          `sudo kubectl apply -f ./engine-private/conf/${deployId}/build/${inputEnv}/proxy.yaml -n ${options.namespace}`,
+        );
+        const secretPath = `./engine-private/conf/${deployId}/build/${inputEnv}/secret.yaml`;
+        if (fs.existsSync(secretPath)) shellExec(`kubectl apply -f ${secretPath} -n ${options.namespace}`);
+      };
+
       if (inputDeployId === 'dd') {
         for (const deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
           const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
           const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
           Underpost.deploy.switchTraffic(deployId, inputEnv, targetTraffic, inputReplicas, options.namespace, options);
+          applyCerts(deployId, targetTraffic);
         }
       } else {
         const currentTraffic = Underpost.deploy.getCurrentTraffic(inputDeployId, { namespace: options.namespace });
@@ -1455,6 +1602,7 @@ EOF
           options.namespace,
           options,
         );
+        applyCerts(inputDeployId, targetTraffic);
       }
     },
     /**
@@ -2097,15 +2245,23 @@ EOF
      * @memberof UnderpostRun
      */
     kill: (path = '', options = DEFAULT_OPTION) => {
-      if (options.pid) return shellExec(`sudo kill -9 ${options.pid}`);
+      if (options.pid)
+        return shellExec(`sudo kill -9 ${options.pid}`, {
+          silentOnError: true,
+        });
       for (const _path of path.split(',')) {
         if (_path.split('+')[1]) {
           let [port, sumPortOffSet] = _path.split('+');
           port = parseInt(port);
           sumPortOffSet = parseInt(sumPortOffSet);
           for (const sumPort of range(0, sumPortOffSet))
-            shellExec(`sudo kill -9 $(lsof -t -i:${parseInt(port) + parseInt(sumPort)})`);
-        } else shellExec(`sudo kill -9 $(lsof -t -i:${_path})`);
+            shellExec(`sudo kill -9 $(lsof -t -i:${parseInt(port) + parseInt(sumPort)})`, {
+              silentOnError: true,
+            });
+        } else
+          shellExec(`sudo kill -9 $(lsof -t -i:${_path})`, {
+            silentOnError: true,
+          });
       }
     },
     /**
@@ -2371,9 +2527,11 @@ EOF`;
     /**
      * @method pull-bundle
      * @description Downloads split zip parts from file storage, merges and extracts them, and moves the result into the public directory.
-     *   Steps: set cron env, download parts (omit-unzip), merge zip, unzip, remove zip, move to public/<host>.
-     * @param {string} path - Optional host name(s) used to locate zip(s) and as public destination(s) (e.g. 'underpost.net' or 'a.com,b.com').
-     *   If omitted, hosts are loaded from `engine-private/conf/<deployId>/conf.server.json`.
+     *   Steps: set env, download parts (omit-unzip), merge zip, unzip, remove zip + parts, move to public/<host>[/path].
+     *   Iterates over every non-singleReplica, non-redirect, non-disabledRebuild route in conf.server.json
+     *   so that multi-path deployments are handled correctly.
+     * @param {string} path - Optional comma-separated host name(s) to restrict processing (e.g. 'underpost.net' or 'a.com,b.com').
+     *   If omitted, all hosts from `engine-private/conf/<deployId>/conf.server.json` are used.
      * @param {Object} options - The default underpost runner options for customizing workflow.
      * @param {string} [options.deployId] - Deploy ID for storage lookup (defaults to 'dd-default').
      * @param {boolean} [options.dev] - Use development environment; defaults to production.
@@ -2384,21 +2542,16 @@ EOF`;
       const env = options.dev ? 'development' : 'production';
       const deployId = options.deployId || 'dd-default';
       const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-      const hosts = path
+      const confServer = fs.existsSync(confServerPath) ? loadConfServerJson(confServerPath) : {};
+      const hostsArg = path
         ? path
             .split(',')
             .map((h) => h.trim())
             .filter(Boolean)
-        : fs.existsSync(confServerPath)
-          ? Object.keys(loadConfServerJson(confServerPath))
-          : [];
+        : Object.keys(confServer);
 
-      if (hosts.length === 0) {
-        logger.error('pull-bundle: no hosts resolved', {
-          deployId,
-          path,
-          confServerPath,
-        });
+      if (hostsArg.length === 0) {
+        logger.error('pull-bundle: no hosts resolved', { deployId, path, confServerPath });
         return;
       }
 
@@ -2407,30 +2560,118 @@ EOF`;
       shellExec(
         `${baseCommand} fs build --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --pull --omit-unzip`,
       );
-      for (const host of hosts) {
-        const zipPath = `build/${host}-.zip`;
-        const hasZip = fs.existsSync(zipPath);
-        const hasParts =
-          fs.existsSync('./build') &&
-          fs
-            .readdirSync('./build')
-            .some((name) => name.startsWith(`${host}-.zip.part`) || name.startsWith(`${host}-.zip-part`));
-
-        if (!hasZip && !hasParts) {
-          logger.warn(`Bundle not found for host '${host}'. Skipping host.`, {
-            zipPath,
-            deployId,
-          });
-          continue;
-        }
 
-        if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
-        shellExec(`${baseCommand} client --unzip ${zipPath}`);
-        shellExec(`sudo rm -rf ${zipPath}`);
-        if (fs.existsSync(`public/${host}`)) shellExec(`sudo rm -rf public/${host}`);
-        shellExec(`sudo mv build/${host} public/${host}`);
+      for (const host of hostsArg) {
+        // Gather all routes for this host; fall back to root '/' when host is not in confServer
+        // (e.g. when hosts were provided explicitly via the path argument).
+        const routePaths = confServer[host] ? Object.keys(confServer[host]) : ['/'];
+
+        for (const routePath of routePaths) {
+          const routeConf = confServer[host] ? confServer[host][routePath] || {} : {};
+          // Skip routes that are not built by buildClient (mirrors buildClient skip conditions)
+          if (routeConf.singleReplica || routeConf.redirect || routeConf.disabledRebuild) continue;
+
+          // buildClient names the zip as "<host>-<path-no-slashes>.zip"
+          // e.g. host="underpost.net", path="/" → buildId="underpost.net-", zip="build/underpost.net-.zip"
+          // e.g. host="app.net", path="/admin" → buildId="app.net-admin", zip="build/app.net-admin.zip"
+          const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+          const zipPath = `build/${buildId}.zip`;
+          const buildDir = './build';
+          const hasZip = fs.existsSync(zipPath);
+          const hasParts =
+            fs.existsSync(buildDir) &&
+            fs
+              .readdirSync(buildDir)
+              .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
+
+          if (!hasZip && !hasParts) {
+            logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
+            continue;
+          }
+
+          if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
+          shellExec(`${baseCommand} client --unzip ${zipPath}`);
+          shellExec(`sudo rm -rf ${zipPath}`);
+
+          // Clean up downloaded part wrapper zips left by --omit-unzip pull
+          if (fs.existsSync(buildDir)) {
+            fs.readdirSync(buildDir)
+              .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
+              .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
+          }
+
+          // unzipClientBuild extracts to buildId with trailing '-' stripped
+          // e.g. "build/underpost.net-" → "build/underpost.net"
+          // e.g. "build/app.net-admin" → "build/app.net-admin" (no trailing dash, no change)
+          const extractedDir = `build/${buildId.replace(/-$/, '')}`;
+          if (!fs.existsSync(extractedDir)) {
+            logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+            continue;
+          }
+
+          // Destination mirrors the public directory layout used by the server
+          const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
+          if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
+          // Ensure parent directory exists for sub-paths
+          if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
+          shellExec(`sudo mv ${extractedDir} ${publicDestPath}`);
+        }
       }
     },
+
+    /**
+     * @method setup-shared-dir
+     * @description Run once for initial shared-directory setup. Creates the group, adds the user,
+     * creates the directory, sets ownership, applies the SGID bit, and configures default ACLs so
+     * all future files inside the directory automatically inherit group write permissions.
+     * Use `reload-shared-dir` for subsequent permission repairs without recreating the group.
+     * @param {string} path - Target directory to set up (defaults to `/home/dd/engine`).
+     *   Customise via the `path` argument or leave empty to use the default.
+     * @param {Object} options - The default underpost runner options for customizing workflow.
+     *   Key fields: `options.user` (default `'admin'`), `options.group` (default `'engine-dev'`).
+     * @memberof UnderpostRun
+     */
+    'setup-shared-dir': (path = '/home/dd/engine', options = DEFAULT_OPTION) => {
+      const dir = path || '/home/dd/engine';
+      const user = options.user || 'admin';
+      const group = options.group || 'engine-dev';
+
+      logger.info(`[setup-shared-dir] dir=${dir} user=${user} group=${group}`);
+
+      shellExec(`sudo groupadd ${group} 2>/dev/null || true`);
+      shellExec(`sudo usermod -aG ${group} ${user}`);
+      shellExec(`sudo mkdir -p ${dir}`);
+      shellExec(`sudo chown -R ${user}:${group} ${dir}`);
+      shellExec(`sudo chmod -R 2775 ${dir}`);
+      shellExec(`sudo setfacl -d -m g:${group}:rwx ${dir}`);
+      shellExec(`sudo setfacl -m g:${group}:rwx ${dir}`);
+
+      logger.info(`[setup-shared-dir] Shared directory setup complete: ${dir}`);
+    },
+
+    /**
+     * @method reload-shared-dir
+     * @description Re-applies recursive permissions and ACLs to repair permission drift on an
+     * already-configured shared directory. Does **not** recreate the group, add users, or modify
+     * ownership. Use this after VS Code permission errors or when existing files lose group write
+     * access due to tool or process interference.
+     * @param {string} path - Target directory to repair (defaults to `/home/dd/engine`).
+     *   Customise via the `path` argument or leave empty to use the default.
+     * @param {Object} options - The default underpost runner options for customizing workflow.
+     *   Key fields: `options.group` (default `'engine-dev'`).
+     * @memberof UnderpostRun
+     */
+    'reload-shared-dir': (path = '/home/dd/engine', options = DEFAULT_OPTION) => {
+      const dir = path || '/home/dd/engine';
+      const group = options.group || 'engine-dev';
+
+      logger.info(`[reload-shared-dir] dir=${dir} group=${group}`);
+
+      shellExec(`sudo chmod -R 2775 ${dir}`);
+      shellExec(`sudo setfacl -R -m g:${group}:rwx ${dir}`);
+
+      logger.info(`[reload-shared-dir] Shared directory permissions reloaded: ${dir}`);
+    },
   };
 
   static API = {

package/src/cli/test.js

@@ -4,6 +4,7 @@
  * @namespace UnderpostTest
  */
 
+import fs from 'fs-extra';
 import { timer } from '../client/components/core/CommonJs.js';
 import { MariaDB } from '../db/mariadb/MariaDB.js';
 import { getNpmRootPath } from '../server/conf.js';
@@ -42,7 +43,13 @@ class UnderpostTest {
      */
     run() {
       actionInitLog();
-      shellExec(`cd ${getNpmRootPath()}/underpost && npm run test`);
+      const underpostTestPath = `${getNpmRootPath()}/underpost`;
+      if (fs.existsSync(underpostTestPath)) {
+        shellExec(`cd ${underpostTestPath} && npm run test`);
+      } else {
+        logger.warn(`Global underpost not found at ${underpostTestPath}, running local npm test instead`);
+        shellExec('npm test');
+      }
     },
     /**
      * @method callback
@@ -148,8 +155,7 @@ class UnderpostTest {
           const pods = Underpost.kubectl.get(podName, kindType);
           let result = pods.find((p) => p.STATUS === status || (status === 'Running' && p.STATUS === 'Completed'));
           logger.info(
-            `Testing pod ${podName}... ${result ? 1 : 0}/1 - elapsed time ${deltaMs * (index + 1)}s - attempt ${
-              index + 1
+            `Testing pod ${podName}... ${result ? 1 : 0}/1 - elapsed time ${deltaMs * (index + 1)}s - attempt ${index + 1
             }/${maxAttempts}`,
             pods[0] ? pods[0].STATUS : 'Not found kind object',
           );

package/src/client/Default.index.js

@@ -19,6 +19,12 @@ const DefaultTemplate = async () => {
     });
   });
   return html`
+    <style>
+      .feature-icon {
+        font-size: 2.5rem;
+        margin-bottom: 1rem;
+      }
+    </style>
     <div class="landing-container">
       <div class="content-wrapper">
         <h1 class="animated-text">
@@ -27,17 +33,17 @@ const DefaultTemplate = async () => {
         </h1>
         <div class="features">
           <div class="feature-card">
-            <i class="icon">🚀</i>
+            <i class="fas fa-rocket feature-icon"></i>
             <h3>Fast &amp; Reliable</h3>
             <p>Lightning-fast performance with 99.9% uptime</p>
           </div>
           <div class="feature-card">
-            <i class="icon">🎨</i>
+            <i class="fas fa-palette feature-icon"></i>
             <h3>Beautiful UI</h3>
             <p>Modern and intuitive user interface</p>
           </div>
           <div class="feature-card">
-            <i class="icon">⚡</i>
+            <i class="fas fa-bolt feature-icon"></i>
             <h3>Powerful Features</h3>
             <p>Everything you need in one place</p>
           </div>