underpost 2.8.885 → 2.8.886

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,20 +125,48 @@ 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`);
@@ -92,21 +185,64 @@ 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 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';
       shellExec(`${baseCommand} run clean`);
@@ -116,16 +252,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,6 +292,13 @@ 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';
@@ -143,31 +307,53 @@ class UnderpostRun {
       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/vs ${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' : ''}`);
-    },
-    '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 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];
+
+      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
@@ -175,11 +361,31 @@ class UnderpostRun {
           versions ? ` --versions ${versions.replaceAll('+', ',')}` : ''
         } dd ${env}`,
       );
-      if (!options.build) shellExec(`${baseCommand} deploy --kubeadm ${deployId} ${env}`);
+
+      if (isDeployRunnerContext(path, options)) {
+        shellExec(`${baseCommand} deploy --kubeadm ${deployId} ${env}`);
+        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 +459,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 +487,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 +510,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,7 +527,13 @@ class UnderpostRun {
       shellExec(`node bin cluster --prom ${hosts.join(',')}`);
       shellExec(`node bin cluster --grafana`);
     },
-
+    /**
+     * @method cluster
+     * @description Deploys a full production-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 deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
       const env = 'production';
@@ -329,50 +561,65 @@ class UnderpostRun {
         shellExec(`underpost deploy ${deployId} ${env} --kubeadm --cert`);
       }
     },
+    /**
+     * @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}`);
+      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}`,
-        );
-      }
-
-      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);
+    },
+
+    /**
+     * @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 || true ? 'node bin' : 'underpost';
 
-      // shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${currentTraffic}`);
+      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 +653,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 +739,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`;

package/src/cli/script.js

@@ -1,3 +1,9 @@
+/**
+ * Script module for managing the execution of scripts.
+ * @module src/cli/script.js
+ * @namespace UnderpostScript
+ */
+
 import { getNpmRootPath } from '../server/conf.js';
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
@@ -6,14 +12,34 @@ import UnderpostDeploy from './deploy.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * @class UnderpostScript
+ * @description Manages the execution of scripts.
+ * @memberof UnderpostScript
+ */
 class UnderpostScript {
   static API = {
+    /**
+     * @method set
+     * @description Sets a script in the package.json file.
+     * @param {string} key - The key for the script.
+     * @param {string} value - The value for the script.
+     * @memberof UnderpostScript
+     */
     set(key, value) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));
       packageJson.scripts[key] = value;
       fs.writeFileSync(`${npmRoot}/package.json`, JSON.stringify(packageJson, null, 4));
     },
+    /**
+     * @method run
+     * @description Runs a script.
+     * @param {string} key - The key for the script.
+     * @param {string} value - The value for the script.
+     * @param {object} options - The options for the script.
+     * @memberof UnderpostScript
+     */
     run(key, value, options) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));
@@ -41,6 +67,12 @@ class UnderpostScript {
       }
       shellExec(`cd ${npmRoot} && npm run ${key}`);
     },
+    /**
+     * @method get
+     * @description Gets a script from the package.json file.
+     * @param {string} key - The key for the script.
+     * @memberof UnderpostScript
+     */
     get(key) {
       const npmRoot = `${getNpmRootPath()}/underpost`;
       const packageJson = JSON.parse(fs.readFileSync(`${npmRoot}/package.json`, 'utf8'));

package/src/cli/secrets.js

@@ -1,14 +1,43 @@
+/**
+ * Secrets module for managing the secrets of the application.
+ * @module src/cli/secrets.js
+ * @namespace UnderpostSecret
+ */
+
 import dotenv from 'dotenv';
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
 import UnderpostRootEnv from './env.js';
 
+dotenv.config();
+
+/**
+ * @class UnderpostSecret
+ * @description Manages the secrets of the application.
+ * @memberof UnderpostSecret
+ */
 class UnderpostSecret {
   static API = {
+    /**
+     * @method docker
+     * @description Manages the secrets of the application.
+     * @memberof UnderpostSecret
+     */
     docker: {
+      /**
+       * @method init
+       * @description Initializes the docker secrets.
+       * @memberof UnderpostSecret
+       */
       init() {
         shellExec(`docker swarm init`);
       },
+      /**
+       * @method createFromEnvFile
+       * @description Creates a secret from an env file.
+       * @param {string} envPath - The path to the env file.
+       * @memberof UnderpostSecret
+       */
       createFromEnvFile(envPath) {
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
         for (const key of Object.keys(envObj)) {
@@ -23,6 +52,11 @@ class UnderpostSecret {
         shellExec(`docker secret ls`);
       },
     },
+    /**
+     * @method underpost
+     * @description Manages the secrets of the application.
+     * @memberof UnderpostSecret
+     */
     underpost: {
       createFromEnvFile(envPath) {
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));