underpost 2.8.885 → 2.81.0

package/src/cli/run.js

@@ -1,6 +1,11 @@
+/**
+ * @description The main entry point for the Underpost CLI applications.
+ * @module src/cli/run.js
+ * @namespace UnderpostRun
+ */
+
 import { daemonProcess, getTerminalPid, openTerminal, pbcopy, shellCd, shellExec } from '../server/process.js';
-import read from 'read';
-import { getNpmRootPath } from '../server/conf.js';
+import { getNpmRootPath, isDeployRunnerContext } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 import UnderpostTest from './test.js';
 import fs from 'fs-extra';
@@ -12,7 +17,33 @@ import os from 'os';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * @class UnderpostRun
+ * @description Manages the execution of various CLI commands and operations.
+ * This class provides a set of static methods to perform different tasks
+ * such as running tests, deploying applications, managing environment variables,
+ * and more. It also includes a default option configuration and a collection of
+ * runners for executing specific commands.
+ * @memberof UnderpostRun
+ */
 class UnderpostRun {
+  /**
+   * @static
+   * @description Default options for the UnderpostRun class.
+   * @type {Object}
+   * @property {boolean} dev - Whether to run in development mode.
+   * @property {string} podName - The name of the pod to run.
+   * @property {string} volumeHostPath - The host path for the volume.
+   * @property {string} volumeMountPath - The mount path for the volume.
+   * @property {string} imageName - The name of the image to run.
+   * @property {string} containerName - The name of the container to run.
+   * @property {string} namespace - The namespace to run in.
+   * @property {boolean} build - Whether to build the image.
+   * @property {number} replicas - The number of replicas to run.
+   * @property {boolean} k3s - Whether to run in k3s mode.
+   * @property {boolean} kubeadm - Whether to run in kubeadm mode.
+   * @memberof UnderpostRun
+   */
   static DEFAULT_OPTION = {
     dev: false,
     podName: '',
@@ -26,7 +57,20 @@ class UnderpostRun {
     k3s: false,
     kubeadm: false,
   };
+  /**
+   * @static
+   * @description Collection of runners for executing specific commands.
+   * @type {Object}
+   * @memberof UnderpostRun
+   */
   static RUNNERS = {
+    /**
+     * @method spark-template
+     * @description Creates a new Spark template project using `sbt new` in `/home/dd/spark-template`, initializes a Git repository, and runs `replace_params.sh` and `build.sh`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'spark-template': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const dir = '/home/dd/spark-template';
       shellExec(`sudo rm -rf ${dir}`);
@@ -47,12 +91,33 @@ class UnderpostRun {
 
       shellCd('/home/dd/engine');
     },
+    /**
+     * @method rmi
+     * @description Forces the removal of all local Podman images (`podman rmi $(podman images -qa) --force`).
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     rmi: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellExec(`podman rmi $(podman images -qa) --force`);
     },
+    /**
+     * @method kill
+     * @description Kills the process running on the specified port by finding its PID using `lsof -t -i:${path}`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the port number).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     kill: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellExec(`sudo kill -9 $(lsof -t -i:${path})`);
     },
+    /**
+     * @method secret
+     * @description Creates an Underpost secret named 'underpost' from a file, defaulting to `/home/dd/engine/engine-private/conf/dd-cron/.env.production` if no path is provided.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the optional path to the secret file).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     secret: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellExec(
         `underpost secret underpost --create-from-file ${
@@ -60,31 +125,62 @@ class UnderpostRun {
         }`,
       );
     },
+    /**
+     * @method underpost-config
+     * @description Calls `UnderpostDeploy.API.configMap` to create a Kubernetes ConfigMap, defaulting to the 'production' environment.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the optional configuration name/environment).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'underpost-config': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       UnderpostDeploy.API.configMap(path ?? 'production');
     },
+    /**
+     * @method gpu-env
+     * @description Sets up a dedicated GPU development environment cluster, resetting and then setting up the cluster with `--dedicated-gpu` and monitoring the pods.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'gpu-env': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellExec(
         `node bin cluster --dev --reset && node bin cluster --dev --dedicated-gpu --kubeadm && kubectl get pods --all-namespaces -o wide -w`,
       );
     },
+    /**
+     * @method tf-gpu-test
+     * @description Deletes existing `tf-gpu-test-script` ConfigMap and `tf-gpu-test-pod`, and applies the test manifest from `manifests/deployment/tensorflow/tf-gpu-test.yaml`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'tf-gpu-test': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const { underpostRoot } = options;
       shellExec(`kubectl delete configmap tf-gpu-test-script`);
       shellExec(`kubectl delete pod tf-gpu-test-pod`);
       shellExec(`kubectl apply -f ${underpostRoot}/manifests/deployment/tensorflow/tf-gpu-test.yaml`);
     },
+    /**
+     * @method dev-cluster
+     * @description Resets and deploys a full development cluster including MongoDB, Valkey, exposes services, and updates `/etc/hosts` for local access.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'dev-cluster': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const baseCommand = options.dev ? 'node bin' : 'underpost';
-      shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --reset`);
-      shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
       const mongoHosts = ['mongodb-0.mongodb-service'];
-      shellExec(
-        `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --mongo-db-host ${mongoHosts.join(
-          ',',
-        )} --pull-image`,
-      );
-      shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --valkey --pull-image`);
+      if (path !== 'expose') {
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --reset`);
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
+
+        shellExec(
+          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --mongo-db-host ${mongoHosts.join(
+            ',',
+          )} --pull-image`,
+        );
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --valkey --pull-image`);
+      }
       shellExec(`${baseCommand} deploy --expose mongo`, { async: true });
       shellExec(`${baseCommand} deploy --expose valkey`, { async: true });
       {
@@ -92,23 +188,91 @@ class UnderpostRun {
         logger.info(hostListenResult.renderHosts);
       }
     },
+    /**
+     * @method ssh-cluster-info
+     * @description Executes the `ssh-cluster-info.sh` script to display cluster connection information.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'ssh-cluster-info': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const { underpostRoot } = options;
-      shellExec(`chmod +x ${underpostRoot}/manifests/maas/ssh-cluster-info.sh`);
-      shellExec(`${underpostRoot}/manifests/maas/ssh-cluster-info.sh`);
+      shellExec(`chmod +x ${underpostRoot}/scripts/ssh-cluster-info.sh`);
+      shellExec(`${underpostRoot}/scripts/ssh-cluster-info.sh`);
     },
+
+    /**
+     * @method dev-hosts-expose
+     * @description Deploys a specified service in development mode with `/etc/hosts` modification for local access.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment ID to deploy).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dev-hosts-expose': (path, options = UnderpostRun.DEFAULT_OPTION) => {
+      shellExec(
+        `node bin deploy ${path} development --disable-update-deployment --disable-update-proxy --kubeadm --etc-hosts`,
+      );
+    },
+
+    /**
+     * @method dev-hosts-restore
+     * @description Restores the `/etc/hosts` file to its original state after modifications made during development deployments.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dev-hosts-restore': (path, options = UnderpostRun.DEFAULT_OPTION) => {
+      shellExec(`node bin deploy --restore-hosts`);
+    },
+
+    /**
+     * @method cyberia-ide
+     * @description Starts the development environment (IDE) for both `cyberia-server` and `cyberia-client` repositories.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'cyberia-ide': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const baseCommand = options.dev ? 'node bin' : 'underpost';
       shellExec(`${baseCommand} run ide /home/dd/cyberia-server`);
       shellExec(`${baseCommand} run ide /home/dd/cyberia-client`);
     },
+    /**
+     * @method engine-ide
+     * @description Starts the development environment (IDE) for the `engine` and `engine-private` repositories.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'engine-ide': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const baseCommand = options.dev ? 'node bin' : 'underpost';
       shellExec(`${baseCommand} run ide /home/dd/engine`);
       shellExec(`${baseCommand} run ide /home/dd/engine/engine-private`);
     },
+    /**
+     * @method cluster-build
+     * @description Build configuration for cluster deployment.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'cluster-build': (path, options = UnderpostRun.DEFAULT_OPTION) => {
+      shellExec(`node bin run clean`);
+      shellExec(`node bin run --dev sync-replica template-deploy`);
+      shellExec(`node bin run sync-replica template-deploy`);
+      shellExec(`node bin env clean`);
+      shellExec(`git add . && underpost cmt . build cluster-build`);
+      shellExec(`cd engine-private && git add . && underpost cmt . build cluster-build`);
+    },
+    /**
+     * @method template-deploy
+     * @description Cleans up, pushes `engine-private` and `engine` repositories with a commit tag `ci package-pwa-microservices-template`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'template-deploy': (path, options = UnderpostRun.DEFAULT_OPTION) => {
-      const baseCommand = options.dev || true ? 'node bin' : 'underpost';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
       shellExec(`${baseCommand} run clean`);
       shellExec(`${baseCommand} push ./engine-private ${process.env.GITHUB_USERNAME}/engine-private`);
       shellCd('/home/dd/engine');
@@ -116,16 +280,37 @@ class UnderpostRun {
       shellExec(`${baseCommand} cmt . --empty ci package-pwa-microservices-template`);
       shellExec(`${baseCommand} push . ${process.env.GITHUB_USERNAME}/engine`);
     },
+    /**
+     * @method clean
+     * @description Changes directory to the provided path (defaulting to `/home/dd/engine`) and runs `node bin/deploy clean-core-repo`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the optional directory path).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     clean: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellCd(path ?? `/home/dd/engine`);
       shellExec(`node bin/deploy clean-core-repo`);
     },
+    /**
+     * @method pull
+     * @description Cleans the core repository and pulls the latest content for `engine` and `engine-private` repositories from the remote.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     pull: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       shellCd(`/home/dd/engine`);
       shellExec(`node bin/deploy clean-core-repo`);
       shellExec(`underpost pull . ${process.env.GITHUB_USERNAME}/engine`);
       shellExec(`underpost pull ./engine-private ${process.env.GITHUB_USERNAME}/engine-private`);
     },
+    /**
+     * @method release-deploy
+     * @description Executes deployment (`underpost run deploy`) for all deployment IDs listed in `./engine-private/deploy/dd.router`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'release-deploy': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       actionInitLog();
       shellExec(`underpost --version`);
@@ -135,51 +320,98 @@ class UnderpostRun {
         shellExec(`underpost run deploy ${deployId}`, { async: true });
       }
     },
+    /**
+     * @method ssh-deploy
+     * @description Performs a Git reset, commits with a message `cd ssh-${path}`, and pushes the `engine` repository, likely triggering an SSH-based CD pipeline.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment identifier for the commit message).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'ssh-deploy': (path, options = UnderpostRun.DEFAULT_OPTION) => {
       actionInitLog();
-      const baseCommand = options.dev || true ? 'node bin' : 'underpost';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
       shellCd('/home/dd/engine');
       shellExec(`git reset`);
       shellExec(`${baseCommand} cmt . --empty cd ssh-${path}`);
       shellExec(`${baseCommand} push . ${process.env.GITHUB_USERNAME}/engine`);
     },
+    /**
+     * @method ide
+     * @description Opens a Visual Studio Code (VS Code) session for the specified path using `node ${underpostRoot}/bin/zed ${path}`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the path to the directory to open in the IDE).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     ide: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const { underpostRoot } = options;
-      shellExec(`node ${underpostRoot}/bin/vs ${path}`);
-    },
-    'dev-client': (_path, options = UnderpostRun.DEFAULT_OPTION) => {
-      let [deployId, hostpath, subConf, lite] = _path.split(',');
-      let [host, path] = hostpath.split('/');
-      if (!path) path = '/';
-      shellExec(`npm run dev-client ${deployId} ${host} ${path} ${subConf} static${lite === 'l' ? ' l' : ''}`);
+      shellExec(`node ${underpostRoot}/bin/zed ${path}`);
     },
-    'dev-api': (path, options = UnderpostRun.DEFAULT_OPTION) => {
-      let [deployId, subConf] = path.split(',');
-      shellExec(`npm run dev-api ${deployId} ${subConf}`);
-    },
-    sync: (path, options = UnderpostRun.DEFAULT_OPTION) => {
+    /**
+     * @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).
+     * @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
+     */
+    sync: async (path, options = UnderpostRun.DEFAULT_OPTION) => {
+      // Dev usage: node bin run --dev --build sync dd-default
       const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev || true ? 'node bin' : 'underpost';
-      shellExec(`${baseCommand} run clean`);
-      const defaultPath = ['dd-default', 1, ``, ``, 'kind-control-plane'];
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const defaultPath = [
+        'dd-default',
+        1,
+        ``,
+        ``,
+        options.dev || !isDeployRunnerContext(path, options) ? 'kind-control-plane' : os.hostname(),
+      ];
       let [deployId, replicas, versions, image, node] = path ? path.split(',') : defaultPath;
-      deployId = deployId ?? defaultPath[0];
-      replicas = replicas ?? defaultPath[1];
-      versions = versions ?? defaultPath[2];
-      image = image ?? defaultPath[3];
-      node = node ?? defaultPath[4];
+      deployId = deployId ? deployId : defaultPath[0];
+      replicas = replicas ? replicas : defaultPath[1];
+      versions = versions ? versions.replaceAll('+', ',') : defaultPath[2];
+      image = image ? image : defaultPath[3];
+      node = node ? node : defaultPath[4];
+
+      if (isDeployRunnerContext(path, options)) {
+        const { validVersion } = UnderpostRepository.API.privateConfUpdate(deployId);
+        if (!validVersion) throw new Error('Version mismatch');
+      }
+
+      const currentTraffic = isDeployRunnerContext(path, options)
+        ? UnderpostDeploy.API.getCurrentTraffic(deployId)
+        : '';
+      let targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : '';
+      if (targetTraffic) versions = targetTraffic;
+
       shellExec(
         `${baseCommand} deploy --kubeadm --build-manifest --sync --info-router --replicas ${
           replicas ?? 1
-        } --node ${node}${image ? ` --image ${image}` : ''}${
-          versions ? ` --versions ${versions.replaceAll('+', ',')}` : ''
-        } dd ${env}`,
+        } --node ${node}${image ? ` --image ${image}` : ''}${versions ? ` --versions ${versions}` : ''} dd ${env}`,
       );
-      if (!options.build) shellExec(`${baseCommand} deploy --kubeadm ${deployId} ${env}`);
+
+      if (isDeployRunnerContext(path, options)) {
+        shellExec(`${baseCommand} deploy --kubeadm --disable-update-proxy ${deployId} ${env} --versions ${versions}`);
+        if (!targetTraffic) targetTraffic = UnderpostDeploy.API.getCurrentTraffic(deployId);
+        await UnderpostDeploy.API.monitorReadyRunner(deployId, env, targetTraffic);
+        UnderpostDeploy.API.switchTraffic(deployId, env, targetTraffic);
+      } else logger.info('current traffic', UnderpostDeploy.API.getCurrentTraffic(deployId));
     },
+    /**
+     * @method ls-deployments
+     * @description Retrieves and logs a table of Kubernetes deployments using `UnderpostDeploy.API.get`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as an optional deployment name filter).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'ls-deployments': async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       console.table(await UnderpostDeploy.API.get(path, 'deployments'));
     },
+    /**
+     * @method monitor
+     * @description Monitors a specific pod (identified by `path`) for the existence of a file (`/await`), and performs conditional actions (like file copying and opening Firefox) when the file is removed.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the name of the pod to monitor).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     monitor: (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const pid = getTerminalPid();
       logger.info('monitor pid', pid);
@@ -253,6 +485,13 @@ class UnderpostRun {
       };
       _monitor();
     },
+    /**
+     * @method db-client
+     * @description Deploys and exposes the Adminer database client application (using `adminer:4.7.6-standalone` image) on the cluster.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'db-client': async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const { underpostRoot } = options;
 
@@ -274,6 +513,13 @@ class UnderpostRun {
         shellExec(`underpost deploy --expose adminer`);
       }
     },
+    /**
+     * @method promote
+     * @description Switches traffic between blue/green deployments for a specified deployment ID(s) (uses `dd.router` for 'dd', or a specific ID).
+     * @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
+     */
     promote: async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       let [inputDeployId, inputEnv, inputReplicas] = path.split(',');
       if (!inputEnv) inputEnv = 'production';
@@ -290,7 +536,13 @@ class UnderpostRun {
         UnderpostDeploy.API.switchTraffic(inputDeployId, inputEnv, targetTraffic, inputReplicas);
       }
     },
-
+    /**
+     * @method metrics
+     * @description Deploys Prometheus and Grafana for metrics monitoring, targeting the hosts defined in the deployment configuration files.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     metrics: async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
       let hosts = [];
@@ -301,78 +553,119 @@ class UnderpostRun {
       shellExec(`node bin cluster --prom ${hosts.join(',')}`);
       shellExec(`node bin cluster --grafana`);
     },
-
-    cluster: async (path, options = UnderpostRun.DEFAULT_OPTION) => {
-      const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
-      const env = 'production';
+    /**
+     * @method cluster
+     * @description Deploys a full production/development ready Kubernetes cluster environment including MongoDB, MariaDB, Valkey, Contour (Ingress), and Cert-Manager, and deploys all services.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    cluster: async (path = '', options = UnderpostRun.DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
       shellCd(`/home/dd/engine`);
-      shellExec(`underpost cluster --reset`);
-      await timer(5000);
-      shellExec(`underpost cluster --kubeadm`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --reset`);
       await timer(5000);
-      shellExec(`underpost dockerfile-pull-base-images --path /home/dd/engine/src/runtime/lampp --kubeadm-load`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm`);
       await timer(5000);
-      shellExec(`underpost cluster --kubeadm --pull-image --mongodb`);
+      let [runtimeImage, deployList] = path.split(',')
+        ? path.split(',')
+        : ['lampp', fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').replaceAll(',', '+')];
+      shellExec(
+        `${baseCommand} dockerfile-pull-base-images${baseClusterCommand}${
+          runtimeImage ? ` --path /home/dd/engine/src/runtime/${runtimeImage}` : ''
+        } --kubeadm-load`,
+      );
+      if (!deployList) {
+        deployList = [];
+        logger.warn('No deploy list provided');
+      } else deployList = deployList.split('+');
       await timer(5000);
-      shellExec(`underpost cluster --kubeadm --pull-image --mariadb`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm --pull-image --mongodb`);
+      if (runtimeImage === 'lampp') {
+        await timer(5000);
+        shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm --pull-image --mariadb`);
+      }
       await timer(5000);
       for (const deployId of deployList) {
-        shellExec(`underpost db ${deployId} --import --git`);
+        shellExec(`${baseCommand} db ${deployId} --import --git`);
       }
       await timer(5000);
-      shellExec(`underpost cluster --kubeadm --pull-image --valkey`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm --pull-image --valkey`);
       await timer(5000);
-      shellExec(`underpost cluster --kubeadm --contour`);
-      await timer(5000);
-      shellExec(`underpost cluster --kubeadm --cert-manager`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm --contour`);
+      if (env === 'production') {
+        await timer(5000);
+        shellExec(`${baseCommand} cluster${baseClusterCommand} --kubeadm --cert-manager`);
+      }
       for (const deployId of deployList) {
-        shellExec(`underpost deploy ${deployId} ${env} --kubeadm --cert`);
+        shellExec(
+          `${baseCommand} deploy ${deployId} ${env} --kubeadm${env === 'production' ? ' --cert' : ''}${
+            env === 'development' ? ' --etc-hosts' : ''
+          }`,
+        );
       }
     },
+    /**
+     * @method deploy
+     * @description Deploys a specified service (identified by `path`) using blue/green strategy, monitors its status, and switches traffic upon readiness.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment ID to deploy).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     deploy: async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const deployId = path;
-      const { validVersion, deployVersion } = UnderpostRepository.API.privateConfUpdate(deployId);
+      const { validVersion } = UnderpostRepository.API.privateConfUpdate(deployId);
       if (!validVersion) throw new Error('Version mismatch');
       const currentTraffic = UnderpostDeploy.API.getCurrentTraffic(deployId);
       const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
       const env = 'production';
       const ignorePods = UnderpostDeploy.API.get(`${deployId}-${env}-${targetTraffic}`).map((p) => p.NAME);
 
-      if (options.build === true) {
-        // deployId, replicas, versions, image, node
-        shellExec(
-          `node bin run sync ${deployId},${options.replicas ?? 1},${targetTraffic},${
-            options.imageName ?? `localhost/rockylinux9-underpost:${deployVersion}`
-          },${os.hostname()}`,
-        );
-      } else shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic}`);
-
-      let checkStatusIteration = 0;
-      const checkStatusIterationMsDelay = 1000;
-      const iteratorTag = `[${deployId}-${env}-${targetTraffic}]`;
-      logger.info('Deployment init', { deployId, env, targetTraffic, checkStatusIterationMsDelay });
-      const minReadyOk = 3;
-      let readyOk = 0;
-
-      while (readyOk < minReadyOk) {
-        const ready = UnderpostDeploy.API.checkDeploymentReadyStatus(deployId, env, targetTraffic, ignorePods).ready;
-        if (ready === true) {
-          readyOk++;
-          logger.info(`${iteratorTag} | Deployment ready. Verification number: ${readyOk}`);
-        }
-        await timer(checkStatusIterationMsDelay);
-        checkStatusIteration++;
-        logger.info(
-          `${iteratorTag} | Deployment in progress... | Delay number check iterations: ${checkStatusIteration}`,
-        );
-      }
+      shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic}`);
 
-      logger.info(`${iteratorTag} | Deployment ready. | Total delay number check iterations: ${checkStatusIteration}`);
+      await UnderpostDeploy.API.monitorReadyRunner(deployId, env, targetTraffic, ignorePods);
 
       UnderpostDeploy.API.switchTraffic(deployId, env, targetTraffic);
+    },
 
-      // shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${currentTraffic}`);
+    /**
+     * @method sync-replica
+     * @description Syncs a replica for the dd.router
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'sync-replica': async (path, options = UnderpostRun.DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+
+      for (let deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
+        deployId = deployId.trim();
+        const _path = '/single-replica';
+        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+        shellExec(`${baseCommand} env ${deployId} ${env}`);
+        for (const host of Object.keys(confServer)) {
+          if (!(_path in confServer[host])) continue;
+          shellExec(`node bin/deploy build-single-replica ${deployId} ${host} ${_path}`);
+          shellExec(`node bin/deploy build-full-client ${deployId}`);
+          const node = options.dev || !isDeployRunnerContext(path, options) ? 'kind-control-plane' : os.hostname();
+          // deployId, replicas, versions, image, node
+          let defaultPath = [deployId, 1, ``, ``, node];
+          shellExec(`${baseCommand} run${options.dev === true ? ' --dev' : ''} --build sync ${defaultPath}`);
+        }
+      }
+      if (isDeployRunnerContext(path, options)) shellExec(`${baseCommand} run promote ${path} production`);
     },
+
+    /**
+     * @method tf-vae-test
+     * @description Creates and runs a job pod (`tf-vae-test`) that installs TensorFlow dependencies, clones the TensorFlow docs, and runs the CVAE tutorial script, with a terminal monitor attached.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'tf-vae-test': async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const { underpostRoot } = options;
       const podName = 'tf-vae-test';
@@ -406,6 +699,13 @@ class UnderpostRun {
         ],
       });
     },
+    /**
+     * @method deploy-job
+     * @description Creates and applies a custom Kubernetes Pod manifest (Job) for running arbitrary commands inside a container image (defaulting to a TensorFlow/NVIDIA image).
+     * @param {string} path - The input value, identifier, or path for the operation (used as the optional script path or job argument).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
     'deploy-job': async (path, options = UnderpostRun.DEFAULT_OPTION) => {
       const podName = options.podName || 'deploy-job';
       const volumeName = `${podName}-volume`;
@@ -485,7 +785,17 @@ EOF`;
       }
     },
   };
+
   static API = {
+    /**
+     * @method callback
+     * @description Initiates the execution of a specified CLI command (runner) with the given input value (`path`) and processed options.
+     * @param {string} runner - The name of the runner to execute.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     * @returns {Promise<any>} The result of the callback execution.
+     */
     async callback(runner, path, options = UnderpostRun.DEFAULT_OPTION) {
       const npmRoot = getNpmRootPath();
       const underpostRoot = options?.dev === true ? '.' : `${npmRoot}/underpost`;