@underpostnet/cyberia 3.2.80

package/src/cli/run.js

@@ -0,0 +1,3326 @@
+/**
+ * @description The main entry point for the Underpost CLI applications.
+ * @module src/cli/run.js
+ * @namespace UnderpostRun
+ */
+
+import { daemonProcess, getTerminalPid, pbcopy, shellCd, shellExec } from '../server/process.js';
+import crypto from 'crypto';
+import {
+  awaitDeployMonitor,
+  buildKindPorts,
+  Config,
+  cronDeployIdResolve,
+  etcHostFactory,
+  getNpmRootPath,
+  isDeployRunnerContext,
+  loadConfInstances,
+  loadConfServerJson,
+  selectConfInstances,
+  loadReplicas,
+  writeEnv,
+} from '../server/conf.js';
+import { actionInitLog, loggerFactory } from '../server/logger.js';
+
+import fs from 'fs-extra';
+import net from 'net';
+import { range, s4, 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) => {
+    let attempts = 0;
+    const tryConnect = () => {
+      attempts++;
+      const socket = net.createConnection({ port, host }, () => {
+        socket.destroy();
+        resolve();
+      });
+      socket.on('error', () => {
+        socket.destroy();
+        if (attempts >= maxAttempts) return reject(new Error(`Port ${port} not ready after ${maxAttempts} attempts`));
+        setTimeout(tryConnect, interval);
+      });
+    };
+    tryConnect();
+  });
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @method instanceProxyRoutesFactory
+ * @description Renders the HTTPProxy route block for every instance sharing a host.
+ * Routes are emitted longest-prefix first so a specific instance path (`/FOREST`)
+ * is never shadowed by the default instance's catch-all (`/`).
+ * @param {string} deployId - Parent deployment identifier.
+ * @param {Array<object>} instances - Expanded instance entries bound to one host.
+ * @param {string} env - `development` | `production`.
+ * @param {Object<string,string>} trafficById - Instance id → traffic colour.
+ * @returns {string} Concatenated route YAML.
+ */
+const instanceProxyRoutesFactory = ({ deployId, instances, env, trafficById }) =>
+  [...instances]
+    .sort((a, b) => (b.path || '/').length - (a.path || '/').length)
+    .map((instance) =>
+      Underpost.deploy.deploymentYamlServiceFactory({
+        path: instance.path,
+        port: env === 'development' && instance.fromDebugPort ? instance.fromDebugPort : instance.fromPort,
+        deployId: `${deployId}-${instance.id}`,
+        env,
+        deploymentVersions: [trafficById[instance.id] || 'blue'],
+        pathRewritePolicy: instance.pathRewritePolicy,
+      }),
+    )
+    .join('');
+
+/**
+ * @constant DEFAULT_OPTION
+ * @description Default options for the UnderpostRun class.
+ * @typedef {Object} UnderpostRunDefaultOptions
+ * @type {Object}
+ * @property {boolean} dev - Whether to run in development mode.
+ * @property {string} podName - The name of the pod to run.
+ * @property {string} nodeName - The name of the node to run.
+ * @property {string} sshKeyPath - Private key path for node SSH operations, forwarded to volume shipping over SSH.
+ * @property {number} port - Custom port to use.
+ * @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 {string} timeoutResponse - The response timeout duration.
+ * @property {string} timeoutIdle - The idle timeout duration.
+ * @property {string} retryCount - The number of retries.
+ * @property {string} retryPerTryTimeout - The timeout duration per retry.
+ * @property {boolean} build - Whether to build the image.
+ * @property {number} replicas - The number of replicas to run.
+ * @property {boolean} force - Whether to force the operation.
+ * @property {boolean} reset - Whether to reset the operation.
+ * @property {boolean} tls - Whether to use TLS.
+ * @property {string} cmd - The command to run in the container.
+ * @property {string} tty - The TTY option for the container.
+ * @property {string} stdin - The stdin option for the container.
+ * @property {string} restartPolicy - The restart policy for the container.
+ * @property {string} runtimeClassName - The runtime class name for the container.
+ * @property {string} imagePullPolicy - The image pull policy for the container.
+ * @property {string} apiVersion - The API version for the container.
+ * @property {string} claimName - The claim name for the volume.
+ * @property {string} kindType - The kind of resource to create.
+ * @property {number} devProxyPortOffset - The port offset for the development proxy.
+ * @property {boolean} hostNetwork - Whether to use host networking.
+ * @property {string} requestsMemory - The memory request for the container.
+ * @property {string} requestsCpu - The CPU request for the container.
+ * @property {string} limitsMemory - The memory limit for the container.
+ * @property {string} limitsCpu - The CPU limit for the container.
+ * @property {string} resourceTemplateId - The resource template ID.
+ * @property {boolean} expose - Whether to expose the service.
+ * @property {boolean} etcHosts - Whether to modify /etc/hosts.
+ * @property {string} confServerPath - The configuration server path.
+ * @property {string} underpostRoot - The root path of the Underpost installation.
+ * @property {string} cmdCronJobs - Pre-script commands to run before cron job execution.
+ * @property {string} deployIdCronJobs - The deployment ID for cron jobs.
+ * @property {string} timezone - The timezone to set.
+ * @property {boolean} kubeadm - Whether to run in kubeadm mode.
+ * @property {boolean} kind - Whether to run in kind mode.
+ * @property {boolean} k3s - Whether to run in k3s mode.
+ * @property {string} hosts - The hosts to use.
+ * @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.
+ * @property {string} monitorStatusKindType - The monitor status kind type option.
+ * @property {string} monitorStatusDeltaMs - The monitor status delta in milliseconds.
+ * @property {string} monitorStatusMaxAttempts - The maximum number of attempts for monitor status.
+ * @property {boolean} logs - Whether to enable logs.
+ * @property {boolean} dryRun - Whether to perform a dry run.
+ * @property {boolean} createJobNow - Whether to create the job immediately.
+ * @property {number} fromNCommit - Number of commits back to use for message propagation (default: 1, last commit only).
+ * @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).
+ * @property {boolean} remove - Whether to remove/teardown resources instead of creating them (e.g. delete-expose for k3s proxy devices in dev-cluster).
+ * @property {boolean} test - Whether to enable test/generic-purpose mode (e.g. use self-signed TLS instead of cert-manager).
+ * @property {string} branch - The Git branch to use for operations (e.g., for template-deploy, ssh-deploy).
+ * @memberof UnderpostRun
+ */
+const DEFAULT_OPTION = {
+  dev: false,
+  podName: '',
+  nodeName: '',
+  sshKeyPath: '',
+  port: 0,
+  volumeHostPath: '',
+  volumeMountPath: '',
+  imageName: '',
+  containerName: '',
+  namespace: 'default',
+  timeoutResponse: '',
+  timeoutIdle: '',
+  retryCount: '',
+  retryPerTryTimeout: '',
+  build: false,
+  replicas: 1,
+  force: false,
+  reset: false,
+  tls: false,
+  cmd: '',
+  tty: '',
+  stdin: '',
+  restartPolicy: '',
+  runtimeClassName: '',
+  imagePullPolicy: '',
+  apiVersion: '',
+  claimName: '',
+  kindType: '',
+  devProxyPortOffset: 0,
+  hostNetwork: false,
+  requestsMemory: '',
+  requestsCpu: '',
+  limitsMemory: '',
+  limitsCpu: '',
+  resourceTemplateId: '',
+  expose: false,
+  etcHosts: false,
+  confServerPath: '',
+  underpostRoot: '',
+  cmdCronJobs: '',
+  deployIdCronJobs: '',
+  timezone: '',
+  kubeadm: false,
+  kind: false,
+  k3s: false,
+  hosts: '',
+  deployId: '',
+  instanceId: '',
+  user: '',
+  group: '',
+  pid: '',
+  disablePrivateConfUpdate: false,
+  monitorStatus: '',
+  monitorStatusKindType: '',
+  monitorStatusDeltaMs: '',
+  monitorStatusMaxAttempts: '',
+  logs: false,
+  dryRun: false,
+  createJobNow: false,
+  fromNCommit: 0,
+  hostAliases: '',
+  gitClean: false,
+  copy: false,
+  skipFullBuild: false,
+  pullBundle: false,
+  remove: false,
+  test: false,
+  branch: '',
+};
+
+/**
+ * @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 Collection of runners for executing specific commands.
+   * @type {Object}
+   * @memberof UnderpostRun
+   */
+  static RUNNERS = {
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dev-cluster': (path, options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const mongoHosts = ['mongodb-0.mongodb-service'];
+      let primaryMongoHost = 'mongodb-0.mongodb-service';
+      if (!options.expose) {
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --reset`);
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
+
+        shellExec(
+          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --service-host ${mongoHosts.join(
+            ',',
+          )} --pull-image`,
+        );
+        shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''} --valkey --pull-image`);
+      }
+      if (options.k3s) {
+        if (options.remove) {
+          shellExec(`${baseCommand} lxd --delete-expose k3s-control:27017`);
+          shellExec(`${baseCommand} lxd --delete-expose k3s-control:6379`);
+        } else {
+          shellExec(`${baseCommand} lxd --expose k3s-control:27017 --node-port 32017`);
+          shellExec(`${baseCommand} lxd --expose k3s-control:6379 --node-port 32079`);
+        }
+        shellExec(`lxc config device show k3s-control`);
+      } else {
+        try {
+          const primaryPodName =
+            MongoBootstrap.getPrimaryPodName({
+              namespace: options.namespace,
+              podName: 'mongodb-0',
+              disableAuth: options.dev,
+            }) || 'mongodb-0';
+          shellExec(
+            `${baseCommand} deploy --expose --namespace ${options.namespace} --disable-update-underpost-config mongo`,
+            { async: true },
+          );
+          shellExec(
+            `${baseCommand} deploy --expose --namespace ${options.namespace} --disable-update-underpost-config valkey`,
+            { async: true },
+          );
+        } catch (error) {
+          logger.warn('Failed to detect MongoDB primary pod, using default', {
+            error: error.message,
+            default: primaryMongoHost,
+          });
+        }
+      }
+      const hostListenResult = etcHostFactory([primaryMongoHost]);
+      logger.info(hostListenResult.renderHosts);
+    },
+
+    /**
+     * @method etc-hosts
+     * @description Modifies the `/etc/hosts` file to add entries for local access to services,
+     * based on the provided path input.
+     * @param {string} path - The input value, identifier, or path for the operation (used to specify the entries to add to /etc/hosts).
+     */
+    'etc-hosts': (path = '', options = DEFAULT_OPTION) => {
+      etcHostFactory(path.split(','));
+    },
+
+    /**
+     * @method ipfs-expose
+     * @description Exposes IPFS Cluster services on specified ports for local access.
+     * @type {Function}
+     * @memberof UnderpostRun
+     */
+    'ipfs-expose': (path, options = DEFAULT_OPTION) => {
+      const ports = [5001, 9094, 8080];
+      for (const port of ports)
+        shellExec(`node bin deploy --expose ipfs-cluster --expose-port ${port} --disable-update-underpost-config`, {
+          async: true,
+        });
+    },
+
+    /**
+     * @method metadata
+     * @description Generates metadata for the specified path after exposing the development cluster.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    metadata: async (path, options = DEFAULT_OPTION) => {
+      const ports = '6379,27017';
+      shellExec(`node bin run kill '${ports}'`);
+      shellExec(`node bin run dev-cluster --dev --expose --namespace ${options.namespace}`, { async: true });
+      logger.info('Waiting for port-forward services to be ready...');
+      try {
+        await Promise.all([waitForPort(27017), waitForPort(6379)]);
+        logger.info('Port-forward services are ready');
+      } catch (err) {
+        logger.error('Port-forward services failed to become ready', { error: err.message });
+        shellExec(`node bin run kill '${ports}'`);
+        throw err;
+      }
+      shellExec(`node bin metadata --generate ${path}`);
+      shellExec(`node bin db --dev --clean-fs-collection dd`);
+      shellExec(`node bin run kill '${ports}'`);
+    },
+
+    /**
+     * @method svc-ls
+     * @description Lists systemd services and installed packages, optionally filtering by the provided path.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the optional filter for services and packages).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'svc-ls': (path, options = DEFAULT_OPTION) => {
+      const log = shellExec(`systemctl list-units --type=service${path ? ` | grep ${path}` : ''}`, {
+        silent: true,
+        stdout: true,
+      });
+      console.log(path ? log.replaceAll(path, path.red) : log);
+      const log0 = shellExec(`sudo dnf list installed${path ? ` | grep ${path}` : ''}`, {
+        silent: true,
+        stdout: true,
+      });
+      console.log(path ? log0.replaceAll(path, path.red) : log0);
+    },
+
+    /**
+     * @method svc-rm
+     * @description Removes a systemd service by stopping it, disabling it, uninstalling the package, and deleting related files.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the service name).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'svc-rm': (path, options = DEFAULT_OPTION) => {
+      shellExec(`sudo systemctl stop ${path}`);
+      shellExec(`sudo systemctl disable --now ${path}`);
+      shellExec(`sudo dnf remove -y ${path}*`);
+      shellExec(`sudo rm -f /usr/lib/systemd/system/${path}.service`);
+      shellExec(`sudo rm -f /etc/yum.repos.d/${path}*.repo`);
+    },
+
+    /**
+     * @method ssh-deploy-info
+     * @description Retrieves deployment status and pod information from a remote server via SSH.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy-info': async (path = '', options = DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      await Underpost.ssh.sshRemoteRunner(
+        `node bin deploy ${path ? path : 'dd'} ${env} --status && kubectl get pods -A`,
+        {
+          deployId: options.deployId,
+          user: options.user,
+          dev: options.dev,
+          remote: true,
+          useSudo: true,
+          cd: '/home/dd/engine',
+        },
+      );
+    },
+
+    /**
+     * @method node-move
+     * @description Abstract runner that relocates any schedulable Kubernetes workload
+     * (Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, CronJob, ReplicationController)
+     * onto a target node by patching its pod-template `nodeSelector` and rolling it out.
+     * Resource-kind agnostic: it resolves the kind dynamically and applies the right
+     * patch path, so it works for `sts`, `deployment`, etc. without bespoke logic.
+     *
+     * Selection grammar via `path`:
+     *   - `<kind>/<name>`  -> a single resource (e.g. `deployment/dd-core-production-blue`)
+     *   - `<kind>`         -> every resource of that kind in the namespace (e.g. `statefulset`)
+     *   - ``               -> all movable workloads (deployment, statefulset, daemonset) in the namespace
+     *
+     * Placement:
+     *   - default: built-in `kubernetes.io/hostname=<node>` (no node mutation required)
+     *   - `--labels k=v,...`: label the target node with those pairs and use them as the
+     *     nodeSelector (matches the "label node + nodeSelector" pattern), enabling reusable
+     *     workload pools instead of pinning to a single hostname.
+     *
+     * Flags: `--node-name <node>` (target), `--namespace <ns>`, `--dry-run` (preview only),
+     *        `--remove` (clear the nodeSelector / unpin placement).
+     *
+     * Caveats: Services/ConfigMaps and bare Pods are not schedulable controllers and are
+     * skipped (move the owning controller). StatefulSets bound to node-local PVs may stay
+     * Pending after a move until their volume is available on the target node.
+     * @param {string} path - Resource selector (`kind/name`, `kind`, or empty).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     * @returns {Array<{ref:string,kind:string,status:string,node?:string}>} Per-resource outcome.
+     */
+    'node-move': (path = '', options = DEFAULT_OPTION) => {
+      const node = options.nodeName;
+      const ns = options.namespace || 'default';
+      const dryRun = options.dryRun === true;
+      const remove = options.remove === true;
+
+      if (!remove && !node) {
+        throw new Error('node-move requires --node-name <target-node> (or --remove to clear placement)');
+      }
+
+      const normalizeKind = (k) =>
+        ({
+          deploy: 'deployment',
+          deployments: 'deployment',
+          deployment: 'deployment',
+          sts: 'statefulset',
+          statefulsets: 'statefulset',
+          statefulset: 'statefulset',
+          ds: 'daemonset',
+          daemonsets: 'daemonset',
+          daemonset: 'daemonset',
+          rs: 'replicaset',
+          replicasets: 'replicaset',
+          replicaset: 'replicaset',
+          rc: 'replicationcontroller',
+          replicationcontroller: 'replicationcontroller',
+          job: 'job',
+          jobs: 'job',
+          cj: 'cronjob',
+          cronjob: 'cronjob',
+          cronjobs: 'cronjob',
+          po: 'pod',
+          pod: 'pod',
+          pods: 'pod',
+          svc: 'service',
+          service: 'service',
+          services: 'service',
+        })[k] || k;
+
+      // Kinds that own a pod template we can patch; rolloutKinds additionally
+      // support `kubectl rollout restart` to reschedule existing pods now.
+      const templated = [
+        'deployment',
+        'statefulset',
+        'daemonset',
+        'replicaset',
+        'job',
+        'cronjob',
+        'replicationcontroller',
+      ];
+      const rolloutKinds = ['deployment', 'statefulset', 'daemonset'];
+      const templateSelectorPath = (kind) =>
+        kind === 'cronjob'
+          ? ['spec', 'jobTemplate', 'spec', 'template', 'spec', 'nodeSelector']
+          : ['spec', 'template', 'spec', 'nodeSelector'];
+
+      // Resolve the desired nodeSelector. Custom --labels enables reusable pools;
+      // otherwise pin by the always-present hostname label.
+      let selector = { 'kubernetes.io/hostname': node };
+      if (!remove && options.labels) {
+        selector = {};
+        for (const pair of `${options.labels}`
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)) {
+          const eq = pair.indexOf('=');
+          if (eq < 0) continue;
+          selector[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+        }
+      }
+
+      // Verify the target node exists, and apply custom labels to it if provided.
+      if (!remove) {
+        const found = shellExec(`kubectl get node ${node} -o name`, {
+          silent: true,
+          stdout: true,
+          silentOnError: true,
+        }).trim();
+        if (!found) throw new Error(`Target node not found: ${node}`);
+        if (options.labels) {
+          const labelArgs = Object.entries(selector)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(' ');
+          const labelCmd = `kubectl label node ${node} ${labelArgs} --overwrite`;
+          if (dryRun) logger.info(`[dry-run] ${labelCmd}`);
+          else shellExec(labelCmd);
+        }
+      }
+
+      const kubectlNames = (kind) =>
+        (
+          shellExec(`kubectl get ${kind} -n ${ns} -o name`, {
+            silent: true,
+            stdout: true,
+            silentOnError: true,
+          }).trim() || ''
+        )
+          .split('\n')
+          .map((s) => s.trim())
+          .filter(Boolean);
+
+      // Build the list of "kind/name" targets from the selection grammar.
+      let targets = [];
+      if (!path) {
+        for (const kind of ['deployment', 'statefulset', 'daemonset']) targets.push(...kubectlNames(kind));
+      } else if (path.includes('/')) {
+        targets = [path];
+      } else {
+        targets = kubectlNames(path);
+      }
+
+      if (targets.length === 0) {
+        logger.warn('node-move: no matching resources found', { path, namespace: ns });
+        return [];
+      }
+
+      // Merge-patch body that sets (or clears, when --remove) the nodeSelector.
+      const buildPatch = (kind) => {
+        const keys = templateSelectorPath(kind);
+        let obj = remove ? null : selector;
+        for (let i = keys.length - 1; i >= 0; i--) obj = { [keys[i]]: obj };
+        return JSON.stringify(obj);
+      };
+
+      const results = [];
+      for (const ref of targets) {
+        const slash = ref.indexOf('/');
+        const rawKind = slash >= 0 ? ref.slice(0, slash) : path && !path.includes('/') ? path : '';
+        const name = slash >= 0 ? ref.slice(slash + 1) : ref;
+        const kind = normalizeKind(`${rawKind}`.split('.')[0].toLowerCase());
+
+        if (!templated.includes(kind)) {
+          logger.warn(`node-move: ${kind}/${name} is not a schedulable controller; skipping`, {
+            hint: 'move its owning controller (deployment/statefulset/daemonset) instead',
+          });
+          results.push({ ref, kind, status: 'skipped' });
+          continue;
+        }
+
+        // Idempotency: skip the patch + rollout if the resource is already where
+        // we want it. Compares the live pod-template nodeSelector against the
+        // desired placement so a repeated run does not trigger an unnecessary
+        // rollout restart.
+        const basePath = kind === 'cronjob' ? 'spec.jobTemplate.spec.template.spec' : 'spec.template.spec';
+        const jsonpath = (expr) =>
+          shellExec(`kubectl get ${kind} ${name} -n ${ns} -o jsonpath='${expr}'`, {
+            silent: true,
+            stdout: true,
+            silentOnError: true,
+            disableLog: true,
+          }).trim();
+
+        if (remove) {
+          const current = jsonpath(`{.${basePath}.nodeSelector}`);
+          if (!current || current === 'map[]') {
+            logger.info(`node-move: ${kind}/${name} already has no nodeSelector; nothing to clear`);
+            results.push({ ref, kind, status: 'already-cleared' });
+            continue;
+          }
+        } else {
+          const alreadyOnNode = Object.entries(selector).every(([k, v]) => {
+            const esc = k.replace(/\./g, '\\.');
+            return jsonpath(`{.${basePath}.nodeSelector.${esc}}`) === v;
+          });
+          if (alreadyOnNode) {
+            logger.info(`node-move: ${kind}/${name} already pinned to ${node}; skipping`, { namespace: ns });
+            results.push({ ref, kind, status: 'already-on-node', node });
+            continue;
+          }
+        }
+
+        const patchCmd = `kubectl patch ${kind} ${name} -n ${ns} --type=merge -p '${buildPatch(kind)}'`;
+        const restartCmd = `kubectl rollout restart ${kind} ${name} -n ${ns}`;
+        if (dryRun) {
+          logger.info(`[dry-run] ${patchCmd}`);
+          if (rolloutKinds.includes(kind)) logger.info(`[dry-run] ${restartCmd}`);
+          results.push({ ref, kind, status: 'dry-run', node: remove ? undefined : node });
+          continue;
+        }
+
+        shellExec(patchCmd);
+        if (rolloutKinds.includes(kind)) shellExec(restartCmd);
+        logger.info(remove ? `Cleared node placement: ${kind}/${name}` : `Moved ${kind}/${name} -> ${node}`, {
+          namespace: ns,
+        });
+        results.push({ ref, kind, status: remove ? 'cleared' : 'moved', node: remove ? undefined : node });
+      }
+
+      logger.info('node-move complete', { namespace: ns, node: remove ? null : node, count: results.length });
+      return results;
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dev-hosts-expose': (path, options = 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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dev-hosts-restore': (path, options = DEFAULT_OPTION) => {
+      shellExec(`node bin deploy --restore-hosts`);
+    },
+
+    /**
+     * @method cluster-build
+     * @description Build configuration for cluster deployment.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'cluster-build': (path, options = DEFAULT_OPTION) => {
+      const nodeOptions =
+        (options.nodeName ? ` --node-name ${options.nodeName}` : '') +
+        (options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '');
+      shellExec(`node bin run clean`);
+      shellExec(`node bin run --dev sync-replica template-deploy${nodeOptions}`);
+      shellExec(`node bin run sync-replica template-deploy${nodeOptions}`);
+      shellExec(`node bin env clean`);
+      for (const deployId of fs.readFileSync('./engine-private/deploy/dd.router', 'utf8').split(','))
+        shellExec(`node bin new --default-conf --deploy-id ${deployId.trim()}`);
+      if (path === 'cmt') {
+        shellExec(`git add . && underpost cmt . build cluster-build`);
+        shellExec(`cd engine-private && git add . && underpost cmt . build cluster-build`);
+      }
+    },
+    /**
+     * @method template-deploy
+     * @description Pushes `engine-private`, dispatches CI workflow to build `pwa-microservices-template`,
+     * and optionally triggers engine-<conf-id> CI with sync/init which in turn dispatches the CD workflow
+     * after the build chain completes (template → ghpkg → engine-<conf-id> → CD).
+     * @param {string} path - The deployment path identifier (e.g., 'sync-engine-core', 'init-engine-core', or empty for build-only).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'template-deploy': (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      shellExec(`npm run security:secrets`);
+      const reportPath = './gitleaks-report.json';
+      if (fs.existsSync(reportPath) && JSON.parse(fs.readFileSync(reportPath, 'utf8')).length > 0) {
+        logger.error('Secrets detected in gitleaks-report.json, aborting template-deploy');
+        return;
+      }
+      shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
+
+      // Capture the sanitized message from the last N commits (--from-n-commit, default 1) for
+      // propagation to pwa-microservices-template and every engine-* repo.
+      const fromN = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+      const sanitizedMessage = shellExec(`node bin cmt --changelog-msg --from-n-commit ${fromN} --changelog-no-hash`, {
+        silent: true,
+        stdout: true,
+      }).trim();
+
+      shellExec(
+        `${baseCommand} push ./engine-private ${options.force ? '-f ' : ''}${
+          process.env.GITHUB_USERNAME
+        }/engine-private`,
+      );
+      shellCd('/home/dd/engine');
+
+      // Push engine repo so workflow YAML changes reach GitHub
+      shellExec(`git reset`);
+      shellExec(`${baseCommand} push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`);
+
+      // Determine deploy conf and type from path (sync-engine-core, init-engine-core, etc.)
+      let deployConfId = '';
+      let deployType = '';
+      if (path.startsWith('sync-')) {
+        deployConfId = path.replace(/^sync-/, '');
+        deployType = 'sync-and-deploy';
+      } else if (path.startsWith('init-')) {
+        deployConfId = path.replace(/^init-/, '');
+        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
+      // the CD workflow after the engine repo build finishes — ensuring correct sequence:
+      // npmpkg.ci → engine-<id>.ci → engine-<id>.cd
+      const repo = `${process.env.GITHUB_USERNAME}/engine`;
+      const inputs = {};
+      if (sanitizedMessage) inputs.message = sanitizedMessage;
+      if (deployConfId) inputs.deploy_conf_id = deployConfId;
+      if (deployType) inputs.deploy_type = deployType;
+
+      // Omit `ref` so dispatchWorkflow auto-detects the repo's default branch
+      // (a fork may default to `main` rather than the monorepo's `master`).
+      Underpost.repo.dispatchWorkflow({
+        repo,
+        workflowFile: 'npmpkg.ci.yml',
+        inputs,
+      });
+    },
+
+    /**
+     * @method template-deploy-local
+     * @description Similar to `template-deploy` but runs the workflow locally without dispatching GitHub Actions. It pulls the latest changes, pushes to GitHub, builds the template, and optionally triggers a local release with CI push.
+     * @param {string} path - The deployment path identifier (e.g., 'sync-engine-core', 'init-engine-core', or empty for build-only).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'template-deploy-local': async (path, options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      shellExec(`npm run security:secrets`);
+      const reportPath = './gitleaks-report.json';
+      if (fs.existsSync(reportPath) && JSON.parse(fs.readFileSync(reportPath, 'utf8')).length > 0) {
+        logger.error('Secrets detected in gitleaks-report.json, aborting template-deploy');
+        return;
+      }
+      shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
+
+      // Capture the sanitized message from the last N commits (--from-n-commit, default 1).
+      const fromN = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+      const sanitizedMessage = shellExec(`node bin cmt --changelog-msg --from-n-commit ${fromN} --changelog-no-hash`, {
+        silent: true,
+        stdout: true,
+      }).trim();
+
+      const { triggerCmd } = path
+        ? await Underpost.release.ci(path, sanitizedMessage, options)
+        : await Underpost.release.pwa(sanitizedMessage, options);
+      pbcopy(triggerCmd + ' && cd /home/dd/engine');
+    },
+    /**
+     * @method docker-image
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'docker-image': (path, options = DEFAULT_OPTION) => {
+      const repo = Underpost.repo.resolveInstanceRepo(path, !options.test);
+      Underpost.repo.dispatchWorkflow({
+        repo,
+        workflowFile: `docker-image${path ? `.${path}` : ''}${options.dev ? '.dev' : ''}.ci.yml`,
+        inputs: {},
+      });
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    clean: (path = '', options = DEFAULT_OPTION) => {
+      Underpost.repo.clean({ paths: path ? path.split(',') : ['/home/dd/engine', '/home/dd/engine/engine-private'] });
+      if (options.dev) shellExec(`node bin run shared-dir ${path ? path : '/home/dd/engine'}`);
+    },
+    /**
+     * @method pull
+     * @description Clones or pulls updates for the `engine` and `engine-private` repositories into `/home/dd/engine` and `/home/dd/engine/engine-private`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @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 });
+      } else {
+        shellExec(`underpost run clean`);
+        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`, {
+          silent: true,
+        });
+      else
+        shellExec(
+          `cd /home/dd/engine/engine-private && underpost pull . ${process.env.GITHUB_USERNAME}/engine-private`,
+          { silent: true },
+        );
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'release-deploy': (path, options = DEFAULT_OPTION) => {
+      actionInitLog();
+      shellExec(`underpost --version`);
+      shellCd(`/home/dd/engine`);
+      for (const _deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
+        const deployId = _deployId.trim();
+        shellExec(`underpost run deploy ${deployId}`, { async: true });
+      }
+    },
+    /**
+     * @method ssh-deploy
+     * @description Dispatches the corresponding CD workflow for SSH-based deployment, replacing empty commits with workflow_dispatch.
+     * @param {string} path - The deployment identifier (e.g., 'engine-core', 'sync-engine-core', 'init-engine-core').
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy': (path, options = DEFAULT_OPTION) => {
+      actionInitLog();
+
+      let job = 'deploy';
+      let confId = path;
+      if (path.startsWith('sync-')) {
+        job = 'sync-and-deploy';
+        confId = path.replace(/^sync-/, '');
+      } else if (path.startsWith('init-')) {
+        job = 'init';
+        confId = path.replace(/^init-/, '');
+      }
+      const repo = Underpost.repo.resolveInstanceRepo(confId, !options.test);
+      // Omit `ref` so dispatchWorkflow auto-detects the target repo's default
+      // branch (getDefaultBranch): the monorepo is `master` but instance repos
+      // like engine-cyberia default to `main` — hardcoding either 422s.
+      Underpost.repo.dispatchWorkflow({
+        repo,
+        workflowFile: `${confId}.cd.yml`,
+        inputs: { job },
+      });
+    },
+    /**
+     * @method ide
+     * @description Opens a Visual Studio Code (VS Code) session for the specified path using `node ${underpostRoot}/bin/zed ${path}`,
+     * or installs Zed and sublime-text IDE if `path` is 'install'.
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    ide: (path = '', options = DEFAULT_OPTION) => {
+      const underpostRoot = options.dev ? '.' : options.underpostRoot;
+      const [projectPath, customIde] = path.split(',');
+      if (projectPath === 'install') {
+        if (customIde === 'zed') shellExec(`sudo curl -f https://zed.dev/install.sh | sh`);
+        else if (customIde === 'subl') {
+          shellExec(
+            `sudo dnf config-manager --add-repo https://download.sublimetext.com/rpm/stable/x86_64/sublime-text.repo`,
+          );
+          shellExec(`sudo dnf install -y sublime-text`);
+        } else {
+          shellExec(`sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc &&
+echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\nautorefresh=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" | sudo tee /etc/yum.repos.d/vscode.repo > /dev/null`);
+          shellExec(`sudo dnf install -y code`);
+        }
+        return;
+      }
+      if (customIde === 'zed') shellExec(`node ${underpostRoot}/bin/zed ${projectPath}`);
+      else shellExec(`node ${underpostRoot}/bin/vs ${projectPath}`);
+    },
+    /**
+     * @method crypto-policy
+     * @description Sets the system's crypto policies to `DEFAULT:SHA1` using `update-crypto-policies` command.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'crypto-policy': (path, options = DEFAULT_OPTION) => {
+      shellExec(`sudo update-crypto-policies --set DEFAULT:SHA1`);
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    sync: async (path, options = DEFAULT_OPTION) => {
+      // Dev usage: node bin run --dev --build sync dd-default
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      const clusterFlag = options.k3s ? ' --k3s' : options.kind ? ' --kind' : ' --kubeadm';
+      const defaultPath = [
+        'dd-default',
+        options.replicas,
+        ``,
+        ``,
+        !options.kubeadm && !options.k3s ? 'kind-control-plane' : os.hostname(),
+      ];
+      let [deployId, replicas, versions, image, node] = path ? path.split(',') : defaultPath;
+      deployId = deployId ? deployId : defaultPath[0];
+      replicas = replicas ? replicas : defaultPath[1];
+      versions = versions ? versions.replaceAll('+', ',') : defaultPath[2];
+      image = image ? image : defaultPath[3];
+      node = node ? node : options.nodeName ? options.nodeName : defaultPath[4];
+      shellExec(`${baseCommand} cluster --ns-use ${options.namespace}`);
+
+      if (image && !image.startsWith('localhost'))
+        Underpost.image.pullDockerHubImage({
+          dockerhubImage: image,
+          kind: options.kind || (!options.nodeName && !options.kubeadm && !options.k3s),
+          kubeadm: options.nodeName || options.kubeadm,
+          k3s: options.k3s,
+        });
+
+      if (isDeployRunnerContext(path, options)) {
+        if (!options.disablePrivateConfUpdate) {
+          const { validVersion } = Underpost.repo.privateConfUpdate(deployId);
+          if (!validVersion) throw new Error('Version mismatch');
+        }
+        if (options.timezone !== 'none') shellExec(`${baseCommand} run${baseClusterCommand} tz`);
+        if (options.deployIdCronJobs !== 'none')
+          shellExec(`node bin cron${baseClusterCommand}${clusterFlag} --setup-start --git --apply`);
+      }
+
+      const currentTraffic = isDeployRunnerContext(path, options)
+        ? Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace })
+        : '';
+      let targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'green';
+      if (targetTraffic) versions = versions ? versions : targetTraffic;
+
+      const ignorePods =
+        isDeployRunnerContext(path, options) && targetTraffic
+          ? Underpost.kubectl.get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace).map((p) => p.NAME)
+          : [];
+
+      const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
+      const cmdString = options.cmd
+        ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
+        : '';
+      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}` : '';
+      const sshKeyPathFlag = options.sshKeyPath ? ` --ssh-key-path ${options.sshKeyPath}` : '';
+
+      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}${skipFullBuildFlag}${pullBundleFlag}${imagePullPolicyFlag}${sshKeyPathFlag} ${deployId} ${env}`,
+      );
+
+      if (isDeployRunnerContext(path, options)) {
+        // Backup app/services repositories with repo-backup configured
+        shellExec(
+          `${baseCommand} db ${deployId} ${clusterFlag}${baseClusterCommand} --repo-backup --primary-pod --git --force-clone --preserveUUID ${options.namespace ? ` --ns ${options.namespace}` : ''}`,
+        );
+        shellExec(
+          `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --node ${node} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
+            options.namespace ? ` --namespace ${options.namespace}` : ''
+          }${timeoutFlags}${gitCleanFlag}${imagePullPolicyFlag}${sshKeyPathFlag}`,
+        );
+        if (!targetTraffic)
+          targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+        await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
+        Underpost.deploy.switchTraffic(deployId, env, targetTraffic, replicas, options.namespace, options);
+      } else
+        logger.info('current traffic', Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }));
+    },
+
+    /**
+     * @method stop
+     * @description Stops a deployment by deleting the corresponding Kubernetes deployment and service resources.
+     * @param {string} path - The input value, identifier, or path for the operation (used to determine which traffic to stop).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    stop: async (path = '', options = DEFAULT_OPTION) => {
+      let currentTraffic = Underpost.deploy.getCurrentTraffic(options.deployId, {
+        namespace: options.namespace,
+        hostTest: options.hosts,
+      });
+      const env = options.dev ? 'development' : 'production';
+
+      if (!path.match('current')) currentTraffic === 'blue' ? (currentTraffic = 'green') : (currentTraffic = 'blue');
+      const [_deployId] = path.split(',');
+      const deploymentId = `${_deployId ? _deployId : options.deployId}${
+        options.instanceId ? `-${options.instanceId}` : ''
+      }-${env}-${currentTraffic}`;
+
+      shellExec(`kubectl delete deployment ${deploymentId} -n ${options.namespace}`);
+      shellExec(`kubectl delete svc ${deploymentId}-service -n ${options.namespace}`);
+    },
+
+    /**
+     * @method ssh-deploy-stop
+     * @description Stops a remote deployment via SSH by executing the appropriate Underpost command on the remote server.
+     * @param {string} path - The input value, identifier, or path for the operation (used to determine which traffic to stop).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy-stop': async (path, options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+
+      const remoteCommand = [
+        `${baseCommand} run${baseClusterCommand} stop${path ? ` ${path}` : ''}`,
+        ` --deploy-id ${options.deployId}${options.instanceId ? ` --instance-id ${options.instanceId}` : ''}`,
+        ` --namespace ${options.namespace}${options.hosts ? ` --hosts ${options.hosts}` : ''}`,
+      ].join('');
+
+      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
+        deployId: options.deployId,
+        user: options.user,
+        dev: options.dev,
+        remote: true,
+        useSudo: true,
+        cd: '/home/dd/engine',
+      });
+    },
+
+    /**
+     * @method ssh-deploy-db-rollback
+     * @description Performs a database rollback on remote deployment via SSH.
+     * @param {string} path - Comma-separated deployId and optional number of commits to reset (format: "deployId,nCommits")
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @param {string} options.deployId - The deployment identifier
+     * @param {string} options.user - The SSH user for credential lookup
+     * @param {boolean} options.dev - Development mode flag
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy-db-rollback': async (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      let [deployId, nCommitsReset] = path.split(',');
+      if (!nCommitsReset) nCommitsReset = 1;
+
+      const remoteCommand = `${baseCommand} db ${deployId} --git --kubeadm --primary-pod --force-clone --macro-rollback-export ${nCommitsReset}${options.namespace ? ` --ns ${options.namespace}` : ''}`;
+
+      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
+        deployId: options.deployId,
+        user: options.user,
+        dev: options.dev,
+        remote: true,
+        useSudo: true,
+        cd: '/home/dd/engine',
+      });
+    },
+
+    /**
+     * @method ssh-deploy-db
+     * @description Imports/restores a database on remote deployment via SSH.
+     * @param {string} path - The deployment ID for database import
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @param {string} options.deployId - The deployment identifier
+     * @param {string} options.user - The SSH user for credential lookup
+     * @param {boolean} options.dev - Development mode flag
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy-db': async (path, options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+
+      const remoteCommand = `${baseCommand} db ${path} --import --drop --preserveUUID --git --kubeadm --primary-pod --force-clone${options.namespace ? ` --ns ${options.namespace}` : ''}`;
+
+      await Underpost.ssh.sshRemoteRunner(remoteCommand, {
+        deployId: options.deployId,
+        user: options.user,
+        dev: options.dev,
+        remote: true,
+        useSudo: true,
+        cd: '/home/dd/engine',
+      });
+    },
+
+    /**
+     * @method ssh-deploy-db-status
+     * @description Retrieves database status/stats for a deployment (or all deployments from dd.router) via SSH.
+     * @param {string} path - Comma-separated deployId(s) or 'dd' to use the dd.router list.
+     * @param {UnderpostRunDefaultOptions} options - Runner options (uses options.deployId for SSH host lookup).
+     * @param {string} options.deployId - Deployment identifier used for SSH config lookup.
+     * @param {string} options.user - SSH user for credential lookup.
+     * @param {boolean} options.dev - Development mode flag.
+     * @param {string} [options.namespace] - Kubernetes namespace to pass to the db check.
+     * @memberof UnderpostRun
+     */
+    'ssh-deploy-db-status': async (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+
+      let deployList = [];
+      if (!path || path === 'dd') {
+        if (!fs.existsSync('./engine-private/deploy/dd.router')) {
+          logger.warn('dd.router not found; nothing to run');
+          return;
+        }
+        deployList = fs
+          .readFileSync('./engine-private/deploy/dd.router', 'utf8')
+          .split(',')
+          .map((d) => d.trim())
+          .filter(Boolean);
+      } else {
+        deployList = path
+          .split(',')
+          .map((d) => d.trim())
+          .filter(Boolean);
+      }
+
+      for (const deployId of deployList) {
+        const remoteCommand = `${baseCommand} db ${deployId} --stats --kubeadm --primary-pod${options.namespace ? ` --ns ${options.namespace}` : ''}`;
+
+        await Underpost.ssh.sshRemoteRunner(remoteCommand, {
+          deployId: options.deployId,
+          user: options.user,
+          dev: options.dev,
+          remote: true,
+          useSudo: true,
+          cd: '/home/dd/engine',
+        });
+      }
+    },
+
+    /**
+     * @method tz
+     * @description Sets the system timezone using `timedatectl set-timezone` command.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the timezone string).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    tz: (path, options = DEFAULT_OPTION) => {
+      const tz =
+        options.timezone && options.timezone !== 'none'
+          ? options.timezone
+          : path
+            ? path
+            : Underpost.env.get('TIME_ZONE', undefined, { disableLog: true })
+              ? Underpost.env.get('TIME_ZONE')
+              : process.env.TIME_ZONE
+                ? process.env.TIME_ZONE
+                : 'America/New_York';
+      shellExec(`sudo timedatectl set-timezone ${tz}`);
+    },
+
+    /**
+     * @method get-proxy
+     * @description Retrieves and logs the HTTPProxy resources in the specified namespace using `kubectl get HTTPProxy`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as an optional filter for the HTTPProxy resources).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'get-proxy': async (path = '', options = DEFAULT_OPTION) => {
+      console.log(
+        shellExec(`kubectl get HTTPProxy -n ${options.namespace} ${path} -o yaml`, {
+          silent: true,
+          stdout: true,
+        })
+          .replaceAll(`blue`, `blue`.bgBlue.bold.black)
+          .replaceAll('green', 'green'.bgGreen.bold.black)
+          .replaceAll('Error', 'Error'.bold.red)
+          .replaceAll('error', 'error'.bold.red)
+          .replaceAll('ERROR', 'ERROR'.bold.red)
+          .replaceAll('Invalid', 'Invalid'.bold.red)
+          .replaceAll('invalid', 'invalid'.bold.red)
+          .replaceAll('INVALID', 'INVALID'.bold.red),
+      );
+    },
+
+    'instance-promote': async (path, options = DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      let [deployId, id] = path.split(',');
+      const confInstances = loadConfInstances(deployId);
+      const promoted = selectConfInstances(confInstances, id);
+      let promotedTraffic = '';
+
+      // A Contour HTTPProxy is named after its host, so every instance sharing a
+      // host shares one object. Rebuilding it from the promoted instance alone
+      // would drop its siblings' routes, so each host is rendered from the full
+      // set: promoted instances flip colour, the rest keep their live colour.
+      const promotedIds = new Set(promoted.map((instance) => instance.id));
+      const hosts = [...new Set(promoted.map((instance) => instance.host))];
+      const affected = confInstances.filter((instance) => hosts.includes(instance.host));
+      const trafficById = {};
+      for (const instance of affected) {
+        const currentTraffic = Underpost.deploy.getCurrentTraffic(`${deployId}-${instance.id}`, {
+          hostTest: instance.host,
+          namespace: options.namespace,
+          env,
+        });
+        if (!promotedIds.has(instance.id)) {
+          trafficById[instance.id] = currentTraffic || 'blue';
+          continue;
+        }
+        trafficById[instance.id] = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
+        promotedTraffic = trafficById[instance.id];
+      }
+
+      for (const host of hosts) {
+        const hostInstances = affected.filter((instance) => instance.host === host);
+        let proxyYaml =
+          Underpost.deploy.baseProxyYamlFactory({ host, env: options.tls ? 'production' : env, options }) +
+          instanceProxyRoutesFactory({ deployId, instances: hostInstances, env, trafficById });
+        if (options.tls) {
+          if (options.test) {
+            const sslDir = `./engine-private/ssl/${host}`;
+            const nameSafe = host.replace(/[^a-zA-Z0-9_.-]/g, '_');
+            fs.mkdirpSync(sslDir);
+            shellExec(`bash ./scripts/ssl.sh "${sslDir}" "${host}"`);
+            shellExec(`kubectl delete secret ${host} -n ${options.namespace} --ignore-not-found`);
+            shellExec(
+              `kubectl create secret tls ${host} --cert="${sslDir}/${nameSafe}.pem" --key="${sslDir}/${nameSafe}-key.pem" -n ${options.namespace}`,
+            );
+          } else {
+            shellExec(`sudo kubectl delete Certificate ${host} -n ${options.namespace} --ignore-not-found`);
+            proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host });
+          }
+        }
+        shellExec(`kubectl delete HTTPProxy ${host} --namespace ${options.namespace} --ignore-not-found`);
+        shellExec(
+          `kubectl apply -f - -n ${options.namespace} <<EOF
+${proxyYaml}
+EOF
+`,
+          { disableLog: true },
+        );
+      }
+      // Refresh the gRPC service to ensure it points to the parent deploy's current traffic.
+      if (promotedTraffic) {
+        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
+          deployId,
+          env,
+          confServer: loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
+          namespace: options.namespace,
+          traffic: [parentTraffic],
+        });
+        if (grpcServicePath) shellExec(`kubectl apply -f ${grpcServicePath} -n ${options.namespace}`);
+      }
+    },
+
+    /**
+     * @method instance
+     * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string containing workflow parameters).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    instance: async (path = '', options = DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      let [deployId, id, replicas] = path.split(',');
+      if (!replicas) replicas = options.replicas;
+      const confInstances = selectConfInstances(loadConfInstances(deployId), id);
+      const etcHosts = [];
+      for (const instance of confInstances) {
+        let {
+          id: _id,
+          host: _host,
+          path: _path,
+          image: _image,
+          fromPort: _fromPort,
+          toPort: _toPort,
+          fromDebugPort: _fromDebugPort,
+          toDebugPort: _toDebugPort,
+          cmd: _cmd,
+          volumes: _volumes,
+          metadata: _metadata,
+          lifecycle: _lifecycle,
+          readinessProbe: _readinessProbe,
+          livenessProbe: _livenessProbe,
+        } = instance;
+        const _deployId = `${deployId}-${_id}`;
+        // Use debug ports in development when defined, fall back to production ports.
+        if (env === 'development' && _fromDebugPort) _fromPort = _fromDebugPort;
+        if (env === 'development' && _toDebugPort) _toPort = _toDebugPort;
+        etcHosts.push(_host);
+        if (options.expose) continue;
+        // Examples images:
+        // `underpost/underpost-engine:${Underpost.version}`
+        // `localhost/rockylinux9-underpost:${Underpost.version}`
+        if (options.imageName) _image = options.imageName;
+        if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
+
+        if (_image && !_image.startsWith('localhost'))
+          Underpost.image.pullDockerHubImage({
+            dockerhubImage: _image,
+            kind: options.kind || (!options.nodeName && !options.kubeadm && !options.k3s),
+            kubeadm: options.nodeName || options.kubeadm,
+            k3s: options.k3s,
+          });
+
+        const currentTraffic = Underpost.deploy.getCurrentTraffic(_deployId, {
+          hostTest: _host,
+          namespace: options.namespace,
+          env,
+        });
+
+        const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
+        const podId = `${_deployId}-${env}-${targetTraffic}`;
+        const ignorePods = Underpost.kubectl.get(podId, 'pods', options.namespace).map((p) => p.NAME);
+        Underpost.deploy.configMap(env, options.namespace);
+        shellExec(`kubectl delete service ${podId}-service --namespace ${options.namespace} --ignore-not-found`);
+        shellExec(`kubectl delete deployment ${podId} --namespace ${options.namespace} --ignore-not-found`);
+        for (const _volume of _volumes)
+          if (_volume.claimName)
+            Underpost.deploy.deployVolume(_volume, {
+              namespace: options.namespace,
+              deployId: _deployId,
+              env,
+              version: targetTraffic,
+              nodeName: Underpost.deploy.resolveDeployNode({
+                node: options.nodeName,
+                kind: options.kind,
+                kubeadm: options.kubeadm,
+                k3s: options.k3s,
+                env,
+              }),
+              clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
+              gitClean: options.gitClean || false,
+              sshKeyPath: options.sshKeyPath || '',
+            });
+        // Regenerate the parent deploy's gRPC ClusterIP service pointing to the
+        // parent's current traffic colour and apply it before the instance pod starts so
+        // DNS is resolvable the moment the pod boots.
+        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
+          deployId,
+          env,
+          confServer: loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
+          namespace: options.namespace,
+          traffic: [targetTraffic],
+          host: _host,
+        });
+        if (grpcServicePath) shellExec(`kubectl apply -f ${grpcServicePath} -n ${options.namespace}`);
+
+        const resolvedCmd = _cmd[env].map((c) =>
+          c.replaceAll(
+            '{{grpc-service-dns}}',
+            `${deployId}-grpc-service-${env}-${parentTraffic}.${options.namespace || 'default'}.svc.cluster.local:50051`,
+          ),
+        );
+
+        // 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({
+    deployId: _deployId,
+    env,
+    suffix: targetTraffic,
+    resources: Underpost.deploy.resourcesFactory(options),
+    replicas,
+    image: _image,
+    namespace: options.namespace,
+    volumes: _volumes,
+    cmd: resolvedCmd,
+    lifecycle: lifecycleForManifest,
+    readinessProbe: pickEnv(_readinessProbe),
+    livenessProbe: pickEnv(_livenessProbe),
+    containerPort: _toPort,
+    imagePullPolicy: instanceImagePullPolicy,
+  })
+  .replace('{{ports}}', buildKindPorts(_fromPort, _toPort))}
+`;
+        // console.log(deploymentYaml);
+        shellExec(
+          `kubectl apply -f - -n ${options.namespace} <<EOF
+${deploymentYaml}
+EOF
+`,
+          { disableLog: true },
+        );
+        // Custom instances run a bare binary (no `underpost start` / internal
+        // HTTP endpoint): Kubernetes readiness is the running signal and
+        // container-status is read via exec. See `Deploy custom instance to K8S.md`.
+        const { ready, readyPods } = await Underpost.monitor.monitorReadyRunner(
+          _deployId,
+          env,
+          targetTraffic,
+          ignorePods,
+          options.namespace,
+          { readyGate: 'kubernetes', statusTransport: 'exec' },
+        );
+
+        if (!ready) {
+          logger.error(`Deployment ${deployId} did not become ready in time.`);
+          return;
+        }
+      }
+      // Promote (switch the HTTPProxy to the new colour) ONLY after EVERY
+      // instance in the family is deployed and ready — never per-instance inside
+      // the loop. A per-variant switch would flip server.cyberiaonline.com to the
+      // default's new deployment while -forest/-test are still being created,
+      // pointing routes at services that don't exist yet. instance-promote
+      // rebuilds the whole host proxy (all variant routes) in one shot, so a
+      // single call with the family id promotes the family atomically.
+      if (!options.expose) await UnderpostRun.RUNNERS['instance-promote'](`${deployId},${id}`, options);
+      if (options.etcHosts) {
+        const hostListenResult = etcHostFactory(etcHosts);
+        logger.info(hostListenResult.renderHosts);
+      }
+    },
+
+    /**
+     * @method deploy-key
+     * @description Copies the deploy key for a specific user and deployId to a temporary location on the local machine.
+     * @param {string} path - The input value, identifier, or path for the operation (not used in this method).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @param {string} options.user - The user for which to copy the deploy key.
+     * @param {string} options.deployId - The deployment identifier associated with the deploy key.
+     * @memberof UnderpostRun
+     */
+    'deploy-key': (path, options = DEFAULT_OPTION) => {
+      const prefix = 'dd-key';
+      if (options.reset) {
+        shellExec(`rm -rf /home/dd/tmp/${prefix}_*`);
+        return;
+      }
+      if (!options.user || !options.deployId) {
+        logger.error('Both --user and --deploy-id options are required to copy the deploy key.');
+        return;
+      }
+      const targetPath = `/home/dd/tmp/${prefix}_${s4()}${s4()}`;
+      fs.mkdirSync('/home/dd/tmp', { recursive: true });
+      fs.copyFileSync(`./engine-private/conf/${options.deployId}/users/${options.user}/id_rsa`, targetPath);
+      logger.info(`Copied deploy key to ${targetPath}`);
+      if (options.copy) pbcopy(targetPath);
+    },
+
+    /**
+     * @method instance-build-manifest
+     * @description Builds a Kubernetes Deployment + Service manifest for a specific instance entry
+     * from `conf.instances.json` and writes it to a file. This is a purely local
+     * artifact generator: it never probes a live cluster. Traffic colour defaults
+     * to the canonical initial `blue` and can be overridden with `--traffic`; the
+     * real blue/green swap is resolved at deploy time (`deploy --sync`).
+     *
+     * If `--build` is supplied the image is built from the project Dockerfile and loaded into the
+     * cluster before the manifest is written (kind by default; `--kubeadm` / `--k3s` override).
+     *
+     * @param {string} path - Comma-separated: `deployId,instanceId[,projectPath]`.
+     *   `projectPath` is the root directory that contains the `Dockerfile` (e.g. `./cyberia-client`).
+     *   Artifacts are written to `<projectPath>/manifests/<env>/Dockerfile` and
+     *   `<projectPath>/manifests/<env>/deployment.yaml`.
+     *   In production, files are also copied to `<projectPath>/Dockerfile` and
+     *   `<projectPath>/deployment.yaml`.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'instance-build-manifest': (path, options = DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      let [deployId, id, projectPath] = path.split(',');
+      const rootPath = projectPath ? projectPath : '.';
+
+      const confInstances = loadConfInstances(deployId);
+      // Targeting a template id builds every world in the family. The fan-out
+      // re-enters this runner with `instanceOnly` because the default world
+      // keeps the template id verbatim — without it, selecting `mmo-server`
+      // would match the family again and recurse forever. Only that default
+      // world publishes to the project root, so the repo keeps exactly one
+      // canonical Dockerfile/deployment.yaml pair.
+      const selected = options.instanceOnly
+        ? confInstances.filter((instance) => instance.id === id)
+        : selectConfInstances(confInstances, id);
+      if (selected.length === 0) {
+        logger.error(`Instance with id '${id}' not found in conf.instances.json for deployId '${deployId}'`);
+        return;
+      }
+      if (!options.instanceOnly && (selected.length > 1 || selected[0].id !== id)) {
+        for (const instance of selected)
+          UnderpostRun.RUNNERS['instance-build-manifest'](
+            [deployId, instance.id, projectPath].filter((v) => v !== undefined).join(','),
+            { ...options, instanceOnly: true },
+          );
+        return;
+      }
+
+      const envManifestPath = `${rootPath}/manifests/deployments/${id}-${env}`;
+      const outputPath = `${envManifestPath}/deployment.yaml`;
+      const dockerfileManifestPath = `${envManifestPath}/Dockerfile`;
+
+      fs.mkdirpSync(envManifestPath);
+
+      const instance = selected[0];
+      const isDefaultInstance = instance.id === instance.templateId || !instance.templateId;
+
+      let {
+        id: _id,
+        host: _host,
+        image: _image,
+        fromPort: _fromPort,
+        toPort: _toPort,
+        fromDebugPort: _fromDebugPort,
+        toDebugPort: _toDebugPort,
+        cmd: _cmd,
+        volumes: _volumes,
+        metadata: _metadata,
+        runtime: _runtime,
+        lifecycle: _lifecycle,
+        readinessProbe: _readinessProbe,
+        livenessProbe: _livenessProbe,
+      } = instance;
+
+      // 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; tried: ${dockerfileCandidates.join(', ')}`);
+      }
+
+      const _deployId = `${deployId}-${_id}`;
+      if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
+      // Use debug ports in development when defined, fall back to production ports.
+      if (env === 'development' && _fromDebugPort) _fromPort = _fromDebugPort;
+      if (env === 'development' && _toDebugPort) _toPort = _toDebugPort;
+
+      // Build image from projectPath Dockerfile and load into cluster when --build is set.
+      if (options.build && projectPath) {
+        const isKind = !options.kubeadm && !options.k3s;
+        Underpost.image.build({
+          path: projectPath,
+          imageName: _image,
+          podmanSave: true,
+          imageOutPath: projectPath,
+          kind: isKind,
+          kubeadm: !!options.kubeadm,
+          k3s: !!options.k3s,
+          reset: !!options.reset,
+          dev: options.dev,
+        });
+        logger.info(`[instance-build-manifest] Image built and loaded`, {
+          image: _image,
+          cluster: isKind ? 'kind' : options.kubeadm ? 'kubeadm' : 'k3s',
+        });
+      }
+
+      const targetTraffic = options.traffic || 'blue';
+      const parentTraffic = targetTraffic;
+      const resolvedCmd = _cmd[env].map((c) =>
+        c.replaceAll(
+          '{{grpc-service-dns}}',
+          `${deployId}-grpc-service-${env}-${parentTraffic}.${options.namespace || 'default'}.svc.cluster.local:50051`,
+        ),
+      );
+
+      // 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
+          .deploymentYamlPartsFactory({
+            deployId: _deployId,
+            env,
+            suffix: targetTraffic,
+            resources: Underpost.deploy.resourcesFactory(options),
+            replicas: options.replicas,
+            image: _image,
+            namespace: options.namespace,
+            volumes: _volumes,
+            cmd: resolvedCmd,
+            lifecycle: lifecycleForManifest,
+            readinessProbe: pickEnv(_readinessProbe),
+            livenessProbe: pickEnv(_livenessProbe),
+            containerPort: _toPort,
+            imagePullPolicy: instanceImagePullPolicy,
+          })
+          .replace('{{ports}}', buildKindPorts(_fromPort, _toPort));
+
+      fs.writeFileSync(outputPath, deploymentYaml, 'utf8');
+      logger.info(`[instance-build-manifest] Manifest written to ${outputPath}`, {
+        deployId: _deployId,
+        env,
+        traffic: targetTraffic,
+        image: _image,
+      });
+
+      // --- Sibling manifests (pv-pvc, proxy, grpc-service) ------------------
+      // Emit the same apply-able set the parent deploy writes to build/<env>,
+      // scoped to this instance so the project repo and engine-private ship
+      // more than just deployment.yaml. Content matches what `run instance`
+      // creates dynamically at deploy time (deployVolume / instance-promote /
+      // the parent gRPC ClusterIP), so a static `kubectl apply` is equivalent.
+      const pvDataNode = Underpost.deploy.resolveDeployNode({
+        node: options.nodeName,
+        kind: options.kind,
+        kubeadm: options.kubeadm,
+        k3s: options.k3s,
+        env,
+      });
+
+      // pv-pvc.yaml — one PV+PVC per instance volume; names mirror deployVolume.
+      let pvPvcYaml = '';
+      for (const volume of _volumes || []) {
+        if (!volume.claimName) continue;
+        const pvcId = `${volume.claimName}-${_deployId}-${env}-${targetTraffic}`;
+        const pvId = `${volume.claimName.replace('pvc-', 'pv-')}-${_deployId}-${env}-${targetTraffic}`;
+        pvPvcYaml += `---\n${Underpost.deploy.persistentVolumeFactory({
+          pvcId,
+          namespace: options.namespace,
+          hostPath: `/home/dd/engine/volume/${pvId}`,
+          nodeName: pvDataNode,
+        })}\n`;
+      }
+
+      // proxy.yaml — this instance's OWN route only (its sub-path → its own
+      // service), so each variant's build dir carries a distinct, instance-scoped
+      // fragment rather than an identical copy of the whole host proxy. The
+      // complete host HTTPProxy — every variant's route aggregated onto the one
+      // fqdn, each pointing at its live colour — is assembled and applied by
+      // `instance-promote` at deploy time, and only once EVERY variant is ready.
+      const proxyYaml =
+        Underpost.deploy.baseProxyYamlFactory({ host: _host, env, options }) +
+        instanceProxyRoutesFactory({
+          deployId,
+          instances: [instance],
+          env,
+          trafficById: { [instance.id]: targetTraffic },
+        });
+
+      // grpc-service.yaml — the parent deploy's gRPC ClusterIP (shared; the
+      // instance cmd resolves {{grpc-service-dns}} to it). Reuse the parent's
+      // generated manifest when present rather than regenerating it here.
+      const parentGrpcServicePath = `./engine-private/conf/${deployId}/build/${env}/grpc-service.yaml`;
+      const grpcServiceYaml = fs.existsSync(parentGrpcServicePath)
+        ? fs.readFileSync(parentGrpcServicePath, 'utf8')
+        : '';
+
+      // Write the sibling set next to deployment.yaml (project) and into the
+      // engine-private per-instance build dir (mirrors instances/<id>/ layout).
+      const instanceBuildDir = `./engine-private/conf/${deployId}/instances/${_id}/build/${env}`;
+      fs.mkdirpSync(instanceBuildDir);
+      fs.writeFileSync(`${instanceBuildDir}/deployment.yaml`, deploymentYaml, 'utf8');
+      const siblingManifests = {
+        'pv-pvc.yaml': pvPvcYaml,
+        'proxy.yaml': proxyYaml,
+        'grpc-service.yaml': grpcServiceYaml,
+      };
+      for (const [name, content] of Object.entries(siblingManifests)) {
+        if (!content) continue;
+        fs.writeFileSync(`${envManifestPath}/${name}`, content, 'utf8');
+        fs.writeFileSync(`${instanceBuildDir}/${name}`, content, 'utf8');
+      }
+      logger.info('[instance-build-manifest] Sibling manifests written', {
+        project: envManifestPath,
+        enginePrivate: instanceBuildDir,
+        pvPvc: !!pvPvcYaml,
+        proxy: !!proxyYaml,
+        grpcService: !!grpcServiceYaml,
+      });
+
+      // --- Per-instance env files -----------------------------------------
+      // Each env file is seeded from the template instance's env file for the
+      // same mode so operator-owned keys (API keys, memory limits, service URLs)
+      // are inherited verbatim; only the keys the instance declares under
+      // `multiInstance.env` — plus the derived container id — are (re)written.
+      //
+      // A derived instance's env dir is generated in full: both development.env
+      // and production.env are written on every build, so a deploy in either
+      // environment always finds the env file its `cmd` sources, no matter which
+      // mode this build ran. The default/template instance owns the committed
+      // source files, so only its current-mode file is idempotently refreshed.
+      if (instance.templateId) {
+        const instanceEnvDir = `./engine-private/conf/${deployId}/instances/${_id}/env`;
+        fs.mkdirpSync(instanceEnvDir);
+        const envsToWrite = isDefaultInstance ? [env] : ['development', 'production'];
+        for (const targetEnv of envsToWrite) {
+          const templateEnvPath = `./engine-private/conf/${deployId}/instances/${instance.templateId}/env/${targetEnv}.env`;
+          const baseEnv = fs.existsSync(templateEnvPath) ? dotenv.parse(fs.readFileSync(templateEnvPath, 'utf8')) : {};
+          writeEnv(`${instanceEnvDir}/${targetEnv}.env`, {
+            ...baseEnv,
+            ...(instance.instanceEnv?.[targetEnv] || {}),
+            CONTAINER_DEPLOY_ID: `${_deployId}-${targetEnv}`,
+          });
+        }
+        logger.info('[instance-build-manifest] Instance env written', {
+          dir: instanceEnvDir,
+          instanceCode: instance.instanceCode,
+          envs: envsToWrite,
+          keys: Object.keys(instance.instanceEnv?.[env] || {}),
+        });
+      }
+
+      if (env === 'production' && isDefaultInstance) {
+        if (fs.existsSync(dockerfileManifestPath)) {
+          fs.copyFileSync(dockerfileManifestPath, `${rootPath}/Dockerfile`);
+        }
+        fs.copyFileSync(outputPath, `${rootPath}/deployment.yaml`);
+        // Sibling manifests alongside deployment.yaml at the project root.
+        for (const name of ['pv-pvc.yaml', 'proxy.yaml', 'grpc-service.yaml']) {
+          const src = `${envManifestPath}/${name}`;
+          if (fs.existsSync(src)) fs.copyFileSync(src, `${rootPath}/${name}`);
+        }
+        logger.info('[instance-build-manifest] Production artifacts copied to project root', {
+          rootPath,
+          dockerfile: `${rootPath}/Dockerfile`,
+          deployment: `${rootPath}/deployment.yaml`,
+        });
+        const ciSrc = `./.github/workflows/docker-image.${_runtime}.ci.yml`;
+        if (fs.existsSync(ciSrc)) {
+          if (!fs.existsSync(`${rootPath}/.github/workflows`)) fs.mkdirpSync(`${rootPath}/.github/workflows`);
+          fs.copyFileSync(ciSrc, `${rootPath}/.github/workflows/docker-image.${_runtime}.ci.yml`);
+          logger.info(`[instance-build-manifest] CI workflow copied`, { src: ciSrc });
+        }
+
+        // Ship the development variant alongside production so the instance repo
+        // is self-contained: the dev Dockerfile (built by the -dev CI workflow
+        // into underpost/<runtime>-dev, consumed by the development compose
+        // stack) and its dispatchable workflow. Both are optional — synced only
+        // when the source-of-truth files exist in the engine repo.
+        if (_runtime) {
+          const devDockerfileSrc = `src/runtime/${_runtime}/Dockerfile.dev`;
+          if (fs.existsSync(devDockerfileSrc)) {
+            fs.copyFileSync(devDockerfileSrc, `${rootPath}/Dockerfile.dev`);
+            logger.info('[instance-build-manifest] Dev Dockerfile copied', { src: devDockerfileSrc });
+          }
+          const devCiSrc = `./.github/workflows/docker-image.${_runtime}.dev.ci.yml`;
+          if (fs.existsSync(devCiSrc)) {
+            if (!fs.existsSync(`${rootPath}/.github/workflows`)) fs.mkdirpSync(`${rootPath}/.github/workflows`);
+            fs.copyFileSync(devCiSrc, `${rootPath}/.github/workflows/docker-image.${_runtime}.dev.ci.yml`);
+            logger.info(`[instance-build-manifest] Dev CI workflow copied`, { src: devCiSrc });
+          }
+        }
+      }
+    },
+
+    /**
+     * @method ls-deployments
+     * @description Retrieves and logs a table of Kubernetes deployments using `Underpost.deploy.get`.
+     * @param {string} path - The input value, identifier, or path for the operation (used as an optional deployment name filter).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'ls-deployments': async (path, options = DEFAULT_OPTION) => {
+      console.table(await Underpost.kubectl.get(path, 'deployments', options.namespace));
+    },
+
+    /**
+     * @method host-update
+     * @description Executes the `rocky-setup.sh` script to update the host system configuration.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'host-update': async (path, options = DEFAULT_OPTION) => {
+      // const baseCommand = options.dev ? 'node bin' : 'underpost';
+      shellExec(`chmod +x ${options.underpostRoot}/scripts/rocky-setup.sh`);
+      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 {UnderpostRunDefaultOptions} 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`);
+      // Add the Kubernetes repo so cri-tools (crictl CLI) is available.
+      // The repo has exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni, so we
+      // use --disableexcludes=kubernetes to override and install cri-tools.
+      shellExec(`cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
+[kubernetes]
+name=Kubernetes
+baseurl=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/
+enabled=1
+gpgcheck=1
+gpgkey=https://pkgs.k8s.io/core:/stable:/v1.36/rpm/repodata/repomd.xml.key
+exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
+EOF`);
+      shellExec(`sudo yum install -y cri-tools --disableexcludes=kubernetes 2>/dev/null || {
+        CRICTL_VERSION="v1.31.0"
+        ARCH="amd64"
+        log "Kubernetes repo not available, downloading crictl binary directly..."
+        curl -sL "https://github.com/kubernetes-sigs/cri-tools/releases/download/\${CRICTL_VERSION}/crictl-\${CRICTL_VERSION}-\${ARCH}.tar.gz" | sudo tar -C /usr/local/bin -xz
+      }`);
+      // 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.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the command to run inside the container).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'dd-container': async (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      const currentImage = options.imageName
+        ? options.imageName
+        : Underpost.image
+            .getCurrentLoaded(options.nodeName ? options.nodeName : 'kind-worker', false)
+            .find((o) => o.IMAGE.match('underpost'));
+      const podName = options.podName || `underpost-dev-container`;
+      const volumeHostPath = options.claimName || '/home/dd';
+      const claimName = options.claimName || `pvc-dd`;
+
+      if (!options.nodeName) {
+        shellExec(`docker exec -i kind-worker bash -c "rm -rf ${volumeHostPath}"`);
+        shellExec(`docker exec -i kind-worker bash -c "mkdir -p ${volumeHostPath}"`);
+        shellExec(`docker cp ${volumeHostPath}/engine kind-worker:${volumeHostPath}/engine`);
+        shellExec(
+          `docker exec -i kind-worker bash -c "chown -R 1000:1000 ${volumeHostPath}; chmod -R 755 ${volumeHostPath}"`,
+        );
+      } else {
+        shellExec(`kubectl apply -f ${options.underpostRoot}/manifests/pv-pvc-dd.yaml -n ${options.namespace}`);
+      }
+
+      if (!currentImage)
+        shellExec(
+          `${baseCommand} image${baseClusterCommand} --pull-base --build --path ${
+            options.dev ? '.' : options.underpostRoot
+          } ${options.dev ? '--kind' : '--kubeadm'}`,
+        );
+      // shellExec(`kubectl delete pod ${podName} --ignore-not-found`);
+
+      const payload = {
+        ...options,
+        podName,
+        imageName: currentImage
+          ? currentImage.image
+            ? currentImage.image
+            : currentImage.IMAGE
+              ? `${currentImage.IMAGE}:${currentImage.TAG}`
+              : `localhost/rockylinux9-underpost:${Underpost.version}`
+          : `localhost/rockylinux9-underpost:${Underpost.version}`,
+        volumeMountPath: volumeHostPath,
+        ...(options.dev ? { volumeHostPath } : { claimName }),
+        on: {
+          init: async () => {},
+        },
+        args: [daemonProcess(path ? path : `cd /home/dd/engine && npm install && npm run test`)],
+      };
+
+      await Underpost.run.CALL('deploy-job', path, payload);
+    },
+
+    /**
+     * @method ip-info
+     * @description Executes the `ip-info.sh` script to display IP-related information for the specified path.
+     * @param {string} path - The input value, identifier, or path for the operation (used as an argument to the script).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'ip-info': (path, options = DEFAULT_OPTION) => {
+      const { underpostRoot } = options;
+      shellExec(`chmod +x ${underpostRoot}/scripts/ip-info.sh`);
+      shellExec(`${underpostRoot}/scripts/ip-info.sh ${path}`);
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'db-client': async (path, options = DEFAULT_OPTION) => {
+      const { underpostRoot } = options;
+
+      Underpost.image.pullDockerHubImage({
+        dockerhubImage: 'adminer',
+        version: '4.7.6-standalone',
+        kind: options.kind,
+        kubeadm: options.kubeadm,
+        k3s: options.k3s,
+      });
+
+      shellExec(`kubectl delete deployment adminer -n ${options.namespace} --ignore-not-found`);
+      shellExec(`kubectl apply -k ${underpostRoot}/manifests/deployment/adminer/. -n ${options.namespace}`);
+      const successInstance = await Underpost.test.statusMonitor('adminer', 'Running', 'pods', 1000, 60 * 10);
+
+      if (successInstance) {
+        shellExec(`underpost deploy --expose adminer --namespace ${options.namespace}`);
+      }
+    },
+
+    /**
+     * @method git-conf
+     * @description Configures Git global and local user name and email settings based on the provided `path` (formatted as `username,email`), or defaults to environment variables.
+     * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated string: `username,email`).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'git-conf': (path = '', options = DEFAULT_OPTION) => {
+      const defaultUsername = Underpost.env.get('GITHUB_USERNAME');
+      const defaultEmail = Underpost.env.get('GITHUB_EMAIL');
+      const validPath = path && path.split(',').length;
+      const [username, email] = validPath ? path.split(',') : [defaultUsername, defaultEmail];
+      if (validPath) {
+        Underpost.env.set('GITHUB_USERNAME', username);
+        Underpost.env.set('GITHUB_EMAIL', email);
+        Underpost.env.get('GITHUB_USERNAME');
+        Underpost.env.get('GITHUB_EMAIL');
+      }
+      shellExec(
+        `git config --global credential.helper "" && ` +
+          `git config credential.helper "" && ` +
+          `git config --global user.name '${username}' && ` +
+          `git config --global user.email '${email}' && ` +
+          `git config --global credential.interactive always && ` +
+          `git config user.name '${username}' && ` +
+          `git config user.email '${email}' && ` +
+          `git config credential.interactive always &&` +
+          `git config pull.rebase false && ` +
+          `git config core.filemode false`,
+        {
+          disableLog: true,
+          silent: true,
+        },
+      );
+
+      if (options.logs)
+        console.log(
+          shellExec(`git config list`, { silent: true, stdout: true })
+            .replaceAll('user.email', 'user.email'.yellow)
+            .replaceAll(username, username.green)
+            .replaceAll('user.name', 'user.name'.yellow)
+            .replaceAll(email, email.green),
+        );
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    promote: async (path, options = DEFAULT_OPTION) => {
+      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 });
+        const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
+        Underpost.deploy.switchTraffic(
+          inputDeployId,
+          inputEnv,
+          targetTraffic,
+          inputReplicas,
+          options.namespace,
+          options,
+        );
+        applyCerts(inputDeployId, targetTraffic);
+      }
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    metrics: async (path, options = DEFAULT_OPTION) => {
+      if (path === 'server') {
+        shellExec(
+          `kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/high-availability-1.21+.yaml`,
+        );
+        await timer(2000);
+
+        shellExec(`kubectl patch deployment metrics-server -n kube-system \
+  --type='json' \
+  -p='[
+    {
+      "op":"add",
+      "path":"/spec/template/spec/containers/0/args/-",
+      "value":"--kubelet-insecure-tls"
+    }
+  ]'`);
+        shellExec(`kubectl scale deployment metrics-server \
+  -n kube-system \
+  --replicas=1`);
+
+        return;
+      }
+      const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
+      let hosts = [];
+      for (const deployId of deployList) {
+        const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
+        hosts = hosts.concat(Object.keys(confServer));
+      }
+      shellExec(`node bin cluster --prom ${hosts.join(',')}`);
+      shellExec(`node bin cluster --grafana`);
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    cluster: async (path = '', options = DEFAULT_OPTION) => {
+      const { underpostRoot } = options;
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      const clusterType = options.k3s ? 'k3s' : 'kubeadm';
+      shellCd(`/home/dd/engine`);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --reset --${clusterType}`);
+      await timer(5000);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType}`);
+      await timer(5000);
+      let [runtimeImage, deployList] =
+        path && path.trim() && path.split(',')
+          ? path.split(',')
+          : [
+              'express',
+              fs.readFileSync(`${underpostRoot}/engine-private/deploy/dd.router`, 'utf8').replaceAll(',', '+'),
+            ];
+      shellExec(
+        `${baseCommand} image${baseClusterCommand} --build ${
+          runtimeImage ? ` --pull-base --path ${underpostRoot}/src/runtime/${runtimeImage}` : ''
+        } --${clusterType}`,
+      );
+      if (!deployList) {
+        deployList = [];
+        logger.warn('No deploy list provided');
+      } else deployList = deployList.split('+');
+      await timer(5000);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --mongodb`);
+      if (runtimeImage === 'lampp') {
+        await timer(5000);
+        shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --mariadb`);
+      }
+      await timer(5000);
+      for (const deployId of deployList) {
+        shellExec(
+          `${baseCommand} db ${deployId} --import --git --drop --preserveUUID --primary-pod${options.namespace ? ` --ns ${options.namespace}` : ''}`,
+        );
+      }
+      await timer(5000);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --pull-image --valkey`);
+      await timer(5000);
+      shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --contour`);
+      if (env === 'production') {
+        await timer(5000);
+        shellExec(`${baseCommand} cluster${baseClusterCommand} --${clusterType} --cert-manager`);
+      }
+      for (const deployId of deployList) {
+        shellExec(
+          `${baseCommand} deploy ${deployId} ${env} --${clusterType}${env === 'production' ? ' --cert' : ''}${
+            env === 'development' ? ' --etc-hosts' : ''
+          }${options.namespace ? ` --namespace ${options.namespace}` : ''}`,
+        );
+      }
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    deploy: async (path, options = DEFAULT_OPTION) => {
+      const deployId = path;
+      const { validVersion } = Underpost.repo.privateConfUpdate(deployId);
+      if (!validVersion) throw new Error('Version mismatch');
+      const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+      const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
+      const env = options.dev ? 'development' : 'production';
+      const ignorePods = Underpost.kubectl
+        .get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace)
+        .map((p) => p.NAME);
+
+      shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic} -n ${options.namespace}`);
+
+      await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
+
+      Underpost.deploy.switchTraffic(deployId, env, targetTraffic, options.replicas, options.namespace, options);
+    },
+
+    /**
+     * @method disk-clean
+     * @description Executes the `disk-clean-sh` script to perform disk cleanup operations.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'disk-clean': async (path, options = DEFAULT_OPTION) => {
+      const { underpostRoot } = options;
+      shellExec(`chmod +x ${underpostRoot}/scripts/disk-clean.sh`);
+      shellExec(`./scripts/disk-clean.sh`);
+    },
+
+    /**
+     * @method disk-devices
+     * @description Executes the `disk-devices.sh` script to display information about disk devices.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'disk-devices': async (path = '/', options = DEFAULT_OPTION) => {
+      const { underpostRoot } = options;
+      shellExec(`chmod +x ${underpostRoot}/scripts/disk-devices.sh`);
+      shellExec(`${underpostRoot}/scripts/disk-devices.sh`);
+    },
+
+    /**
+     * @method disk-usage
+     * @description Displays disk usage statistics using the `du` command, sorted by size.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'disk-usage': async (path = '/', options = DEFAULT_OPTION) => {
+      if (!path) path = '/';
+      logger.info('Mount filesystem');
+      shellExec(`df -h${path === '/' ? '' : ` ${path}`}`);
+      logger.info('Files disks usage');
+      shellExec(`du -xh ${path} --max-depth=1 | sort -h`);
+    },
+
+    /**
+     * @method dev
+     * @description Starts development servers for client, API, and proxy based on provided parameters (deployId, host, path, clientHostPort).
+     * @param {string} path - The input value, identifier, or path for the operation (formatted as `deployId,subConf,host,path,clientHostPort`).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    dev: async (path = '', options = DEFAULT_OPTION) => {
+      let [deployId, subConf, host, _path, clientHostPort] = path.split(',');
+      if (options.confServerPath) {
+        const confServer = JSON.parse(fs.readFileSync(options.confServerPath, 'utf8'));
+        fs.writeFileSync(
+          `./engine-private/conf/${deployId}/conf.server.dev.${subConf}.json`,
+          JSON.stringify(
+            {
+              [host]: {
+                [_path]: confServer[host][_path],
+              },
+            },
+            null,
+            4,
+          ),
+          'utf8',
+        );
+      }
+      if (!deployId) deployId = 'dd-default';
+      if (!host) host = 'default.net';
+      if (!_path) _path = '/';
+      if (!clientHostPort) clientHostPort = 'localhost:4004';
+      if (!subConf) subConf = 'local';
+      if (options.reset && fs.existsSync(`./engine-private/conf/${deployId}`))
+        fs.removeSync(`./engine-private/conf/${deployId}`);
+      if (options.devProxyPortOffset) {
+        const envPath = `./engine-private/conf/${deployId}/.env.development`;
+        const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
+        envObj.DEV_PROXY_PORT_OFFSET = options.devProxyPortOffset;
+        writeEnv(envPath, envObj);
+      }
+      dotenv.config({ path: `./engine-private/conf/${deployId}/.env.development`, override: true });
+      shellExec(`node bin run dev-cluster --expose --namespace ${options.namespace}`, { async: true });
+      {
+        const cmd = `npm run dev:api ${deployId} ${subConf} ${host} ${_path} ${clientHostPort} proxy${
+          options.tls ? ' tls' : ''
+        }`;
+        shellExec(cmd, { async: true });
+      }
+      if ((await awaitDeployMonitor()) !== true) return;
+      {
+        const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
+
+        shellExec(cmd, {
+          async: true,
+        });
+      }
+      if ((await awaitDeployMonitor()) !== true) return;
+      shellExec(
+        `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
+      );
+    },
+
+    /**
+     * @method service
+     * @description Deploys and exposes specific services (like `mongo-express-service`) on the cluster, updating deployment configurations and monitoring status.
+     * @param {string} path - The input value, identifier, or path for the operation (formatted as `deployId,serviceId,host,path,replicas,image,node`).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    service: async (path = '', options = DEFAULT_OPTION) => {
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      shellCd(`/home/dd/engine`);
+      let [deployId, serviceId, host, _path, replicas, image, node] = path.split(',');
+      if (!replicas) replicas = options.replicas;
+      // const confClient = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.client.json`, 'utf8'));
+      const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
+      // const confSSR = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.ssr.json`, 'utf8'));
+      // const packageData = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/package.json`, 'utf8'));
+      const services = fs.existsSync(`./engine-private/deploy/${deployId}/conf.services.json`)
+        ? JSON.parse(fs.readFileSync(`./engine-private/deploy/${deployId}/conf.services.json`, 'utf8'))
+        : [];
+      let serviceData = services.findIndex((s) => s.serviceId === serviceId);
+      const payload = {
+        serviceId,
+        path: _path,
+        port: options.port,
+        host,
+      };
+      let podToMonitor;
+      if (!payload.port)
+        switch (serviceId) {
+          case 'mongo-express-service': {
+            payload.port = 8081;
+            break;
+          }
+          case 'grafana': {
+            payload.port = 3000;
+            // payload.pathRewritePolicy = [
+            //   {
+            //     prefix: '/grafana',
+            //     replacement: '/',
+            //   },
+            // ];
+            break;
+          }
+        }
+      if (serviceData == -1) {
+        services.push(payload);
+      } else {
+        services[serviceData] = payload;
+      }
+      fs.writeFileSync(
+        `./engine-private/conf/${deployId}/conf.services.json`,
+        JSON.stringify(services, null, 4),
+        'utf8',
+      );
+      switch (serviceId) {
+        case 'mongo-express-service': {
+          shellExec(`kubectl delete svc mongo-express-service -n ${options.namespace} --ignore-not-found`);
+          shellExec(`kubectl delete deployment mongo-express -n ${options.namespace} --ignore-not-found`);
+          shellExec(`kubectl apply -f manifests/deployment/mongo-express/deployment.yaml -n ${options.namespace}`);
+          podToMonitor = 'mongo-express';
+          break;
+        }
+        case 'grafana': {
+          shellExec(
+            `node bin cluster${baseClusterCommand} --grafana --hosts '${host}' --prom '${Object.keys(confServer)}'`,
+          );
+          podToMonitor = 'grafana';
+          break;
+        }
+      }
+      const success = await Underpost.test.statusMonitor(podToMonitor);
+      if (success) {
+        const versions = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        if (!node) node = os.hostname();
+        const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
+        shellExec(
+          `${baseCommand} deploy${options.dev ? '' : ' --kubeadm'}${
+            options.devProxyPortOffset ? ' --disable-deployment-proxy' : ''
+          } --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
+            image ? ` --image ${image}` : ''
+          }${versions ? ` --versions ${versions}` : ''}${timeoutFlags} dd ${env}`,
+        );
+        shellExec(
+          `${baseCommand} deploy${options.dev ? '' : ' --kubeadm'}${
+            options.devProxyPortOffset ? ' --disable-deployment-proxy' : ''
+          } --disable-update-deployment ${deployId} ${env} --versions ${versions}`,
+        );
+      } else logger.error(`Service pod ${podToMonitor} failed to start in time.`);
+      if (options.etcHosts === true) {
+        const hostListenResult = etcHostFactory([host]);
+        logger.info(hostListenResult.renderHosts);
+      }
+    },
+
+    /**
+     * @method etc-hosts
+     * @description Generates and logs the contents for the `/etc/hosts` file based on provided hosts or deployment configurations.
+     * @param {string} path - The input value, identifier, or path for the operation (used as a comma-separated list of hosts).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'etc-hosts': async (path = '', options = DEFAULT_OPTION) => {
+      const hosts = path ? path.split(',') : [];
+      if (options.deployId) {
+        const confServer = loadConfServerJson(`./engine-private/conf/${options.deployId}/conf.server.json`);
+        hosts.push(...Object.keys(confServer));
+      }
+      const hostListenResult = etcHostFactory(hosts);
+      logger.info(hostListenResult.renderHosts);
+    },
+
+    /**
+     * @method sh
+     * @description Enables remote control for the Kitty terminal emulator.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    sh: async (path = '', options = DEFAULT_OPTION) => {
+      let [operator, arg0, arg1] = path.split(',');
+      if (operator == 'copy') {
+        shellExec(
+          `kitty @ get-text ${arg0 === 'all' ? '--match all' : '--self'} --extent all${
+            arg1 === 'ansi' ? ' --ansi yes' : ''
+          } | kitty +kitten clipboard`,
+        );
+        return;
+      }
+      shellExec(`kitty -o allow_remote_control=yes`);
+    },
+
+    /**
+     * @method log
+     * @description Searches and highlights keywords in a specified log file, optionally showing surrounding lines.
+     * @param {string} path - The input value, identifier, or path for the operation (formatted as `filePath,keywords,lines`).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    log: async (path, options = DEFAULT_OPTION) => {
+      const [filePath, keywords, lines] = path.split(',');
+      let result = shellExec(`grep -i -E ${lines ? `-C ${lines} ` : ''}'${keywords}' ${filePath}`, {
+        stdout: true,
+        silent: true,
+      }).replaceAll(`--`, `==============================`.green.bold);
+      for (const keyword of keywords.split('|')) result = result.replaceAll(keyword, keyword.bgYellow.black.bold);
+      console.log(result);
+    },
+
+    /**
+     * @method ps
+     * @description Displays running processes that match a specified path or keyword.
+     * @param {string} path - The input value, identifier, or path for the operation (used as a keyword to filter processes).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    ps: async (path = '', options = DEFAULT_OPTION) => {
+      const out = shellExec(
+        path.startsWith('top-consumers')
+          ? `ps -eo pid,%cpu,%mem,rss,cmd --sort=-%cpu | head -n ${path.split(',')[1] || 15}`
+          : path
+            ? `(ps -eo pid,%cpu,%mem,rss,cmd -ww | head -n1; ps -eo pid,%cpu,%mem,rss,cmd -ww | tail -n +2 | grep -F ${path})`
+            : `ps -eo pid,%cpu,%mem,rss,cmd -ww`,
+        {
+          stdout: true,
+          silent: true,
+        },
+      );
+
+      console.log(
+        path ? out.replaceAll(path.split(',')[2] || path, (path.split(',')[2] || path).bgYellow.black.bold) : out,
+      );
+    },
+
+    /**
+     * @method pid-info
+     * @description Displays detailed information about a process by PID, including service details, command line, executable path, working directory, environment variables, and parent process tree.
+     * @param {string} path - The PID of the process to inspect.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'pid-info': (path, options = DEFAULT_OPTION) => {
+      const pid = path;
+      if (!pid) {
+        logger.error('PID is required. Usage: underpost run pid-info <pid>');
+        return;
+      }
+
+      // Services
+      logger.info('Process info');
+      shellExec(`sudo ps -p ${pid} -o pid,ppid,user,stime,etime,cmd`);
+      logger.info('Command line');
+      shellExec(`sudo cat /proc/${pid}/cmdline | tr '\\0' ' ' ; echo`);
+      logger.info('Executable path');
+      shellExec(`sudo readlink -f /proc/${pid}/exe`);
+      logger.info('Working directory');
+      shellExec(`sudo readlink -f /proc/${pid}/cwd`);
+      logger.info('Environment variables (first 200)');
+      shellExec(`sudo tr '\\0' '\\n' </proc/${pid}/environ | head -200`);
+
+      // Parent
+      logger.info('Parent process');
+      const parentInfo = shellExec(`sudo ps -o pid,ppid,user,cmd -p ${pid}`, { stdout: true, silent: true });
+      console.log(parentInfo);
+      const ppidMatch = parentInfo.split('\n').find((l) => l.trim().startsWith(pid));
+      if (ppidMatch) {
+        const ppid = ppidMatch.trim().split(/\s+/)[1];
+        logger.info(`Parent PID: ${ppid}`);
+        shellExec(`ps -fp ${ppid}`);
+      }
+      logger.info('Process tree');
+      shellExec(`pstree -s ${pid}`);
+    },
+
+    /**
+     * @method background
+     * @description Runs a custom command in the background using nohup, logging output to `/var/log/<id>.log` and saving the PID to `/var/run/<id>.pid`.
+     * @param {string} path - The command to run in the background (e.g. 'npm run prod:container dd-cyberia-r3').
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    background: (path, options = DEFAULT_OPTION) => {
+      if (!path) {
+        logger.error('Command is required. Usage: underpost run background <command>');
+        return;
+      }
+      const id = path.split(/\s+/).pop();
+      const logFile = `/var/log/${id}.log`;
+      const pidFile = `/var/run/${id}.pid`;
+      logger.info(`Starting background process`, { id, logFile, pidFile });
+      shellExec(`nohup ${path} > ${logFile} 2>&1 & pid=$!; echo $pid > ${pidFile}; disown`);
+      logger.info(`Background process started for '${id}'`);
+    },
+
+    /**
+     * @method ports
+     * @description Set on ~/.bashrc alias: ports <port> Command to list listening ports that match the given keyword.
+     * @param {string} path - The input value, identifier, or path for the operation (used as a keyword to filter listening ports).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    ports: async (path = '', options = DEFAULT_OPTION) => {
+      shellExec(`chmod +x ${options.underpostRoot}/scripts/ports-ls.sh`);
+      shellExec(`${options.underpostRoot}/scripts/ports-ls.sh`);
+    },
+
+    /**
+     * @method deploy-test
+     * @description Deploys a test deployment (`dd-test`) in either development or production mode, setting up necessary secrets and starting the deployment.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment ID).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'deploy-test': async (path, options = DEFAULT_OPTION) => {
+      // Note: use recomendation empty deploy cluster: node bin --dev cluster
+      const env = options.dev ? 'development' : 'production';
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseClusterCommand = options.dev ? ' --dev' : '';
+      const inputs = path ? path.split(',') : [];
+      const deployId = inputs[0] ? inputs[0] : 'dd-test';
+      const cmd = options.cmd
+        ? options.cmd
+        : [
+            `npm install -g npm@11.2.0`,
+            `npm install -g underpost`,
+            `${baseCommand} secret underpost --create-from-env`,
+            `${baseCommand} start --build --run ${deployId} ${env}`,
+          ];
+      shellExec(`node bin run sync${baseClusterCommand} --deploy-id-cron-jobs none dd-test --cmd "${cmd}"`);
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'tf-vae-test': async (path, options = DEFAULT_OPTION) => {
+      const podName = 'tf-vae-test';
+      await Underpost.run.CALL('deploy-job', '', {
+        logs: options.logs,
+        podName,
+        // volumeMountPath: '/custom_images',
+        // volumeHostPath: '/home/dd/engine/src/client/public/cyberia/assets/skin',
+        on: {
+          init: async () => {
+            // const pid = getTerminalPid();
+            // shellExec(`sudo kill -9 ${pid}`);
+            (async () => {
+              const nameSpace = options.namespace;
+              const basePath = '/home/dd';
+              const scriptPath = '/site/en/tutorials/generative/cvae.py';
+
+              const { close } = await (async () => {
+                const checkAwaitPath = '/await';
+                while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
+                  logger.info('monitor', checkAwaitPath);
+                  await timer(1000);
+                }
+
+                return {
+                  close: () => shellExec(`sudo kubectl exec -i ${podName} -- sh -c "rm -rf ${checkAwaitPath}"`),
+                };
+              })();
+
+              const localScriptPath = `${basePath}/lab/src/${scriptPath.split('/').pop()}`;
+              if (!fs.existsSync(localScriptPath)) {
+                throw new Error(`Local override script not found: ${localScriptPath}`);
+              }
+
+              shellExec(`sudo kubectl cp ${localScriptPath} ${nameSpace}/${podName}:${basePath}/docs${scriptPath}`);
+
+              close();
+
+              {
+                const checkPath = `/latent_space_plot.png`;
+                const outsPaths = [];
+                const labDir = `${basePath}/lab`;
+
+                logger.info('monitor', checkPath);
+                {
+                  const checkAwaitPath = `/home/dd/docs${checkPath}`;
+                  while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
+                    logger.info('waiting for', checkAwaitPath);
+                    await timer(1000);
+                  }
+                }
+
+                {
+                  const toPath = `${labDir}${checkPath}`;
+                  outsPaths.push(toPath);
+                  shellExec(`sudo kubectl cp ${nameSpace}/${podName}:${basePath}/docs${checkPath} ${toPath}`);
+                }
+
+                for (let i of range(1, 10)) {
+                  const fileName = `image_at_epoch_${setPad(i, '0', 4)}.png`;
+                  const fromPath = `/${fileName}`;
+                  const toPath = `${labDir}/${fileName}`;
+                  outsPaths.push(toPath);
+                  shellExec(`sudo kubectl cp ${nameSpace}/${podName}:${basePath}/docs${fromPath} ${toPath}`);
+                }
+
+                shellExec(`firefox ${outsPaths.join(' ')}`);
+                process.exit(0);
+              }
+            })();
+          },
+        },
+        args: [
+          `pip install --upgrade \
+               nbconvert \
+               tensorflow-probability==0.23.0 \
+               imageio \
+               git+https://github.com/tensorflow/docs \
+               matplotlib \
+               "numpy<1.25,>=1.21"`,
+          'mkdir -p /home/dd',
+          'cd /home/dd',
+          'git clone https://github.com/tensorflow/docs.git',
+          'cd docs',
+          'jupyter nbconvert --to python site/en/tutorials/generative/cvae.ipynb',
+          `echo '' > /await`,
+          `echo '=== WAITING SCRIPT LAUNCH ==='`,
+          `while [ -f /await ]; do sleep 1; done`,
+          `echo '=== FINISHED ==='`,
+          daemonProcess(`ipython site/en/tutorials/generative/cvae.py`),
+        ],
+      });
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'spark-template': (path, options = DEFAULT_OPTION) => {
+      const dir = '/home/dd/spark-template';
+      shellExec(`sudo rm -rf ${dir}`);
+      shellCd('/home/dd');
+
+      // pbcopy(`cd /home/dd && sbt new ${process.env.GITHUB_USERNAME}/spark-template.g8`);
+      // await read({ prompt: 'Command copy to clipboard, press enter to continue.\n' });
+      shellExec(`cd /home/dd && sbt new ${process.env.GITHUB_USERNAME}/spark-template.g8 '--name=spark-template'`);
+
+      shellCd(dir);
+
+      Underpost.repo.initLocalRepo({ path: dir });
+      shellExec(`git add . && git commit -m "Base implementation"`);
+      shellExec(`chmod +x ./replace_params.sh`);
+      shellExec(`chmod +x ./build.sh`);
+
+      shellExec(`./replace_params.sh`);
+      shellExec(`./build.sh`);
+
+      shellCd('/home/dd/engine');
+    },
+    /**
+     * @method pull-rocky-image
+     * @description Pulls the base `rockylinux:9` image from Docker Hub via Podman.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'pull-rocky-image': (path, options = DEFAULT_OPTION) => {
+      shellExec(`sudo podman pull docker.io/library/rockylinux:9`);
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    rmi: (path, options = DEFAULT_OPTION) => {
+      shellExec(`podman rmi $(podman images -qa) --force`);
+    },
+    /**
+     * @method kill
+     * @description Kills processes listening on the specified port(s). If the `path` contains a `+`, it treats it as a range of ports to kill.
+     * @param {string} path - The input value, identifier, or path for the operation (used as the port number).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    kill: (path = '', options = DEFAULT_OPTION) => {
+      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(
+              `PIDS=$(lsof -t -i:${parseInt(port) + parseInt(sumPort)}); [ -n "$PIDS" ] && sudo kill -9 $PIDS || true`,
+              {
+                silentOnError: true,
+              },
+            );
+        } else
+          shellExec(`PIDS=$(lsof -t -i:${_path}); [ -n "$PIDS" ] && sudo kill -9 $PIDS || true`, {
+            silentOnError: true,
+          });
+      }
+    },
+    /**
+     * @method generate-pass
+     * @description Generates a cryptographically secure random password that satisfies all validatePassword
+     * constraints (lowercase, uppercase, digit, special char, min 8 chars). Logs the plain password
+     * to the console or, when `--copy` is set, copies it to the clipboard via pbcopy.
+     * @param {string} path - Optional password length (default: 16).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
+     * @param {boolean} options.copy - When true, copies to clipboard instead of logging.
+     * @memberof UnderpostRun
+     */
+    'generate-pass': (path, options = DEFAULT_OPTION) => {
+      const length = path && parseInt(path) > 0 ? parseInt(path) : 16;
+      const lower = 'abcdefghijklmnopqrstuvwxyz';
+      const upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+      const digits = '0123456789';
+      const special = '@#$%^&*()_+';
+      const all = lower + upper + digits + special;
+      const buf = crypto.randomBytes(length + 4);
+      // Guarantee at least one character from each required class
+      const chars = [
+        lower[buf[0] % lower.length],
+        upper[buf[1] % upper.length],
+        digits[buf[2] % digits.length],
+        special[buf[3] % special.length],
+      ];
+      for (let i = 4; i < length; i++) chars.push(all[buf[i] % all.length]);
+      // Fisher-Yates shuffle using an independent random buffer
+      const shuf = crypto.randomBytes(length);
+      for (let i = chars.length - 1; i > 0; i--) {
+        const j = shuf[i % shuf.length] % (i + 1);
+        [chars[i], chars[j]] = [chars[j], chars[i]];
+      }
+      const password = chars.join('');
+      if (options.copy) pbcopy(password);
+      else console.log(password);
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    secret: (path, options = DEFAULT_OPTION) => {
+      const cronDeployId = cronDeployIdResolve() || 'dd-cron';
+      Underpost.secret.underpost.createFromEnvFile(
+        `/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${options.dev ? 'development' : 'production'}`,
+      );
+    },
+    /**
+     * @method underpost-config
+     * @description Calls `Underpost.deploy.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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'underpost-config': (path = '', options = DEFAULT_OPTION) => {
+      Underpost.deploy.configMap(path ? path : 'production', options.namespace);
+    },
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'gpu-env': (path, options = DEFAULT_OPTION) => {
+      const clusterType = 'kubeadm';
+      shellExec(
+        `node bin cluster --dev --reset --${clusterType} && node bin cluster --dev --dedicated-gpu --${clusterType} && 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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'tf-gpu-test': (path, options = DEFAULT_OPTION) => {
+      const { underpostRoot, namespace } = options;
+      shellExec(`kubectl delete configmap tf-gpu-test-script -n ${namespace} --ignore-not-found`);
+      shellExec(`kubectl delete pod tf-gpu-test-pod -n ${namespace} --ignore-not-found`);
+      shellExec(`kubectl apply -f ${underpostRoot}/manifests/deployment/tensorflow/tf-gpu-test.yaml -n ${namespace}`);
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'deploy-job': async (path, options = DEFAULT_OPTION) => {
+      const podName = options.podName || 'deploy-job';
+      const volumeName = `${podName}-volume`;
+      if (typeof options.args === 'string') options.args = options.args.split(',');
+      const args = (options.args ? options.args : path ? [path] : [`python ${path}`]).filter((c) => c.trim());
+      const imageName = options.imageName || 'nvcr.io/nvidia/tensorflow:24.04-tf2-py3';
+      const containerName = options.containerName || `${podName}-container`;
+      const gpuEnable = imageName.match('nvidia');
+      const runtimeClassName = options.runtimeClassName ? options.runtimeClassName : gpuEnable ? 'nvidia' : '';
+      const namespace = options.namespace || 'default';
+      const volumeMountPath = options.volumeMountPath || path;
+      const volumeHostPath = options.volumeHostPath || path;
+      const claimName = options.claimName || '';
+      const enableVolumeMount = volumeMountPath && (volumeHostPath || claimName);
+      const tty = options.tty ? 'true' : 'false';
+      const stdin = options.stdin ? 'true' : 'false';
+      const restartPolicy = options.restartPolicy || 'Never';
+      const kindType = options.kindType || 'Pod';
+      const imagePullPolicy = options.imagePullPolicy || 'IfNotPresent';
+      const hostNetwork = options.hostNetwork ? options.hostNetwork : '';
+      const apiVersion = options.apiVersion || 'v1';
+      // Parse hostAliases option:
+      //   - string from CLI: "ip1=host1,host2;ip2=host3,host4"
+      //   - array from programmatic callers: [{ ip: "127.0.0.1", hostnames: ["foo.local"] }]
+      const hostAliases = options.hostAliases
+        ? Array.isArray(options.hostAliases)
+          ? options.hostAliases
+          : options.hostAliases
+              .split(';')
+              .filter((entry) => entry.trim())
+              .map((entry) => {
+                const [ip, hostnamesStr] = entry.split('=');
+                const hostnames = hostnamesStr ? hostnamesStr.split(',').map((h) => h.trim()) : [];
+                return { ip: ip.trim(), hostnames };
+              })
+        : [];
+      const hostAliasesYaml =
+        hostAliases.length > 0
+          ? `  hostAliases:\n${hostAliases
+              .map(
+                (alias) =>
+                  `  - ip: "${alias.ip}"\n    hostnames:\n${alias.hostnames.map((h) => `    - "${h}"`).join('\n')}`,
+              )
+              .join('\n')}`
+          : '';
+      const labels = options.labels
+        ? options.labels
+            .split(',')
+            .map((keyValue) => {
+              const [key, value] = keyValue.split('=');
+              return `    ${key}: ${value}
+`;
+            })
+            .join('')
+        : `    app: ${podName}`;
+      if (options.volumeType === 'dev') options.volumeType = 'FileOrCreate';
+      const volumeType =
+        options.volumeType || (enableVolumeMount && volumeHostPath && fs.statSync(volumeHostPath).isDirectory())
+          ? 'Directory'
+          : 'File';
+
+      const envs = Underpost.env.list();
+
+      const cmd = `kubectl apply -f - <<EOF
+apiVersion: ${apiVersion}
+kind: ${kindType}
+metadata:
+  name: ${podName}
+  namespace: ${namespace}
+  labels:
+${labels}
+spec:
+  restartPolicy: ${restartPolicy}
+${runtimeClassName ? `  runtimeClassName: ${runtimeClassName}` : ''}
+${hostNetwork ? `  hostNetwork: ${hostNetwork}` : ''}
+${hostAliasesYaml}
+  containers:
+    - name: ${containerName}
+      image: ${imageName}
+      imagePullPolicy: ${imagePullPolicy}
+      tty: ${tty}
+      stdin: ${stdin}
+      command: ${JSON.stringify(options.cmd ? options.cmd : ['/bin/bash', '-c'])}
+${
+  args.length > 0
+    ? `      args:
+        - |
+${args.map((arg) => `          ${arg}`).join('\n')}`
+    : ''
+}
+${`${
+  gpuEnable
+    ? `      resources:
+        limits:
+          nvidia.com/gpu: '1'
+`
+    : ''
+}      env:
+${Object.keys(envs)
+  .map((key) => ({ key, value: typeof envs[key] === 'number' ? envs[key] : `"${envs[key]}"` }))
+  .concat(gpuEnable ? [{ key: 'NVIDIA_VISIBLE_DEVICES', value: 'all' }] : [])
+  .map((env) => `        - name: ${env.key}\n          value: ${env.value}`)
+  .join('\n')}`}
+${
+  enableVolumeMount
+    ? Underpost.deploy.volumeFactory([{ volumeMountPath, volumeName, volumeHostPath, volumeType, claimName }]).render
+    : ''
+}
+EOF`;
+      shellExec(`kubectl delete pod ${podName} -n ${namespace} --ignore-not-found`);
+      console.log(cmd);
+      shellExec(cmd, { disableLog: true });
+      const successInstance = await Underpost.test.statusMonitor(
+        podName,
+        options.monitorStatus || 'Running',
+        options.monitorStatusKindType || 'pods',
+        options.monitorStatusDeltaMs || 1000,
+        options.monitorStatusMaxAttempts || 600,
+      );
+      if (successInstance) {
+        options.on?.init ? await options.on.init() : null;
+        if (options.logs) shellExec(`kubectl logs -f ${podName} -n ${namespace}`, { async: true });
+      }
+    },
+
+    /**
+     * @method push-bundle
+     * @description Builds the client zip for the specified deployment, splits it into parts, and uploads to file storage.
+     *   Steps: set env, build+split zip, upload only the zip parts belonging to the deploy-id's hosts (from conf.server.json).
+     *   Only files matching `<host>-<route>.zip.part*` or `<host>-<route>.zip` for each non-skipped route are uploaded.
+     * @param {string} path - Optional `fsPath.splitOption` string.
+     *   Examples: `build` (default split 8), `build.16` (split 16 MB), `build.none-split` (no split flag).
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
+     * @param {string} [options.deployId] - Override deploy ID.
+     * @param {boolean} [options.dev] - Use development environment; defaults to production.
+     * @memberof UnderpostRun
+     */
+    'push-bundle': (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
+      const env = options.dev ? 'development' : 'production';
+      const deployId = options.deployId || 'dd-default';
+      const pathParts = (path || '').split('.');
+      const fsPath = (pathParts[0] || '').trim() || 'build';
+      const splitOption = (pathParts[1] || '').trim();
+
+      let splitFlag = '--split 8';
+      if (splitOption) {
+        if (splitOption === 'none-split') {
+          splitFlag = '';
+        } else {
+          const splitMb = Number(splitOption);
+          if (Number.isFinite(splitMb) && splitMb > 0) {
+            splitFlag = `--split ${splitMb}`;
+          } else {
+            logger.warn('push-bundle: invalid split option, using default split 8', {
+              path,
+              splitOption,
+            });
+          }
+        }
+      }
+
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
+      const storageFilePath = `engine-private/conf/${deployId}/storage.bundle.json`;
+
+      shellExec(`${baseCommand} env ${deployId} ${env}`);
+      shellExec(`${baseCommand} client ${deployId} --build-zip${splitFlag ? ` ${splitFlag}` : ''}`);
+
+      const pushBundleFiles = (host, routePath) => {
+        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+        const buildDir = `./${fsPath}`;
+        if (!fs.existsSync(buildDir)) return;
+        const partFiles = fs
+          .readdirSync(buildDir)
+          .filter(
+            (name) =>
+              name.startsWith(`${buildId}.zip.part`) ||
+              name.startsWith(`${buildId}.zip-part`) ||
+              name === `${buildId}.zip`,
+          )
+          .map((name) => `${fsPath}/${name}`);
+        if (partFiles.length === 0) {
+          logger.warn(`push-bundle: no bundle files found for '${host}${routePath}'`, { buildId });
+          return;
+        }
+        for (const partFile of partFiles) {
+          shellExec(
+            `${baseCommand} fs ${partFile} --deploy-id ${deployId} --storage-file-path ${storageFilePath} --force`,
+          );
+        }
+      };
+
+      for (const host of Object.keys(confServer)) {
+        for (const routePath of Object.keys(confServer[host])) {
+          const routeConf = confServer[host][routePath] || {};
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pushBundleFiles(host, replica);
+              }
+            }
+            continue;
+          }
+          pushBundleFiles(host, routePath);
+        }
+      }
+    },
+
+    /**
+     * @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 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 {UnderpostRunDefaultOptions} 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.
+     * @memberof UnderpostRun
+     */
+    'pull-bundle': (path = '', options = DEFAULT_OPTION) => {
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
+      const env = options.dev ? 'development' : 'production';
+      const deployId = options.deployId || 'dd-default';
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
+      const hostsArg = path
+        ? path
+            .split(',')
+            .map((h) => h.trim())
+            .filter(Boolean)
+        : Object.keys(confServer);
+
+      if (hostsArg.length === 0) {
+        logger.error('pull-bundle: no hosts resolved', { deployId, path, confServerPath });
+        return;
+      }
+
+      shellExec(`${baseCommand} env ${deployId} ${env}`);
+      if (!fs.existsSync('./build')) fs.mkdirSync('./build', { recursive: true });
+      shellExec(
+        `${baseCommand} fs build --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --pull --omit-unzip`,
+      );
+
+      const pullBundleRoute = (host, routePath) => {
+        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 });
+          return;
+        }
+
+        if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
+        shellExec(`${baseCommand} client --unzip ${zipPath}`);
+        shellExec(`sudo rm -rf ${zipPath}`);
+
+        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}`));
+        }
+
+        const extractedDir = `build/${buildId.replace(/-$/, '')}`;
+        if (!fs.existsSync(extractedDir)) {
+          logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+          return;
+        }
+
+        const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
+        if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
+        if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
+        fs.copySync(`${extractedDir}`, `${publicDestPath}`);
+      };
+
+      for (const host of hostsArg) {
+        const routePaths = confServer[host] ? Object.keys(confServer[host]) : ['/'];
+
+        for (const routePath of routePaths) {
+          const routeConf = confServer[host] ? confServer[host][routePath] || {} : {};
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pullBundleRoute(host, replica);
+              }
+            }
+            continue;
+          }
+          pullBundleRoute(host, routePath);
+        }
+      }
+    },
+
+    /**
+     * @method build-cluster-deployment-manifests
+     * @description Builds deployment manifests for both production and development environments using `node bin deploy --build-manifest`, syncing them, and setting replicas to 1 for the `dd` deployment.
+     * @param {string} path - Unused.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
+     * @memberof UnderpostRun
+     */
+    'build-cluster-deployment-manifests': (path = '', options = DEFAULT_OPTION) => {
+      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd development`);
+      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd production --cert`);
+    },
+
+    /**
+     * @method monitor-ui
+     * @description Installs and enables the Cockpit KVM Dashboard (cockpit, cockpit-machines, libvirt)
+     * and opens the cockpit firewall service. With `--remove`, closes the firewall service instead.
+     * @param {string} path - Unused.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
+     *   `options.remove` — when true, removes the cockpit firewall rule instead of adding it.
+     * @memberof UnderpostRun
+     */
+    'monitor-ui': (path, options = DEFAULT_OPTION) => {
+      if (options.remove) {
+        shellExec(`sudo firewall-cmd --zone=public --remove-service=cockpit --permanent`);
+        shellExec(`sudo firewall-cmd --reload`);
+        return;
+      }
+      shellExec(`sudo dnf install -y cockpit cockpit-machines libvirt`);
+      shellExec(`sudo systemctl enable --now cockpit.socket libvirtd`);
+      shellExec(`sudo firewall-cmd --permanent --add-service=cockpit`);
+      shellExec(`sudo firewall-cmd --reload`);
+    },
+
+    /**
+     * @method 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 {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow.
+     *   Key fields: `options.user` (default `'admin'`), `options.group` (default `'engine-dev'`).
+     * @memberof UnderpostRun
+     */
+    '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 shared-dir-add-user
+     * @description Add a user to an existing shared directory without changing
+     * file owners. Grants recursive group/ACL access so the user can read and
+     * write throughout the shared workspace while preserving existing ownership.
+     *
+     * @param {string} path - Shared directory (defaults to `/home/dd/engine`).
+     * @param {UnderpostRunDefaultOptions} options - Underpost runner options.
+     *   Key fields:
+     *     - options.user  (default: 'admin')
+     *     - options.group (default: 'engine-dev')
+     *
+     * @memberof UnderpostRun
+     */ 'shared-dir-add-user': (path = '/home/dd/engine', options = DEFAULT_OPTION) => {
+      const dir = path || '/home/dd/engine';
+      const user = options.user || 'admin';
+
+      logger.info(`[shared-dir-add-user] dir=${dir} user=${user}`);
+
+      // Give the user direct access without changing owners or group ownership.
+      shellExec(`sudo setfacl -R -m u:${user}:rwx ${dir}`);
+
+      // Make future files/directories inherit the same user ACL.
+      shellExec(`sudo find ${dir} -type d -exec setfacl -d -m u:${user}:rwx {} \\;`);
+
+      logger.info(`[shared-dir-add-user] User '${user}' added to shared directory: ${dir}`);
+    },
+  };
+
+  static API = {
+    /**
+     * @method DEFAULT_OPTION
+     * @description The default options for Underpost runners, including development mode, namespace, replicas, and underpost root path.
+     * @memberof UnderpostRun
+     * @static
+     * @returns {Object} The default options object.
+     */
+    get DEFAULT_OPTION() {
+      return DEFAULT_OPTION;
+    },
+    /**
+     * @method RUNNERS
+     * @description Retrieves the list of available runner IDs from the UnderpostRun class.
+     * @memberof UnderpostRun
+     * @returns {string[]} An array of runner IDs.
+     */
+    get RUNNERS() {
+      return Object.keys(UnderpostRun.RUNNERS);
+    },
+
+    /**
+     * @method CALL
+     * @description Executes a specified runner function from the UnderpostRun class with the provided path and options.
+     * @param {string} runner - The name of the runner to execute.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     * @returns {Promise<any>} The result of the runner execution.
+     */
+    async CALL(runner = '', path = '', options = DEFAULT_OPTION) {
+      return await UnderpostRun.RUNNERS[runner](path, options);
+    },
+
+    /**
+     * @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 {UnderpostRunDefaultOptions} 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 = DEFAULT_OPTION) {
+      try {
+        const npmRoot = getNpmRootPath();
+        const underpostRoot = options?.dev === true ? '.' : `${npmRoot}/underpost`;
+        if (options.cmd) options.cmd = options.cmd.split(',');
+        if (options.args) options.args = options.args.split(',');
+        if (!options.underpostRoot) options.underpostRoot = underpostRoot;
+        if (!options.namespace) options.namespace = 'default';
+        if (options.replicas === '' || options.replicas === null || options.replicas === undefined)
+          options.replicas = 1;
+        options.npmRoot = npmRoot;
+        logger.info(`Executing runner`, { runner, namespace: options.namespace });
+        if (!Underpost.run.RUNNERS.includes(runner)) throw new Error(`Runner not found: ${runner}`);
+        const result = await Underpost.run.CALL(runner, path, options);
+        return result;
+      } catch (error) {
+        console.log(error);
+        logger.error(error);
+        process.exit(1);
+      }
+    },
+  };
+}
+
+export default UnderpostRun;