cyberia 3.0.3 → 3.2.5

package/src/cli/run.js

@@ -4,24 +4,45 @@
  * @namespace UnderpostRun
  */
 
-import { daemonProcess, getTerminalPid, openTerminal, shellCd, shellExec } from '../server/process.js';
+import { daemonProcess, getTerminalPid, pbcopy, shellCd, shellExec } from '../server/process.js';
+import crypto from 'crypto';
 import {
   awaitDeployMonitor,
   buildKindPorts,
   Config,
   getNpmRootPath,
   isDeployRunnerContext,
+  loadConfServerJson,
   writeEnv,
 } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 
 import fs from 'fs-extra';
+import net from 'net';
 import { range, setPad, timer } from '../client/components/core/CommonJs.js';
 
 import os from 'os';
 import Underpost from '../index.js';
 import dotenv from 'dotenv';
 
+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);
 
 /**
@@ -55,7 +76,6 @@ const logger = loggerFactory(import.meta);
  * @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 {boolean} terminal - Whether to open a terminal.
  * @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.
@@ -87,6 +107,7 @@ const logger = loggerFactory(import.meta);
  * @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"] }]).
@@ -120,7 +141,6 @@ const DEFAULT_OPTION = {
   apiVersion: '',
   claimName: '',
   kindType: '',
-  terminal: false,
   devProxyPortOffset: 0,
   hostNetwork: false,
   requestsMemory: '',
@@ -152,7 +172,10 @@ const DEFAULT_OPTION = {
   logs: false,
   dryRun: false,
   createJobNow: false,
+  fromNCommit: 0,
   hostAliases: '',
+  gitClean: false,
+  copy: false,
 };
 
 /**
@@ -195,7 +218,7 @@ class UnderpostRun {
       }
 
       {
-        // Detect MongoDB primary pod using centralized method
+        // Detect MongoDB primary pod using method
         let primaryMongoHost = 'mongodb-0.mongodb-service';
         try {
           const primaryPodName = Underpost.db.getMongoPrimaryPodName({
@@ -245,8 +268,15 @@ class UnderpostRun {
       const ports = '6379,27017';
       shellExec(`node bin run kill '${ports}'`);
       shellExec(`node bin run dev-cluster --dev --expose --namespace ${options.namespace}`, { async: true });
-      console.log('Loading fordward services...');
-      await timer(5000);
+      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}'`);
@@ -355,58 +385,140 @@ class UnderpostRun {
     },
     /**
      * @method template-deploy
-     * @description Cleans up, pushes `engine-private` and `engine` repositories with a commit tag `ci package-pwa-microservices-template`.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @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 {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'template-deploy': (path = '', options = DEFAULT_OPTION) => {
       const baseCommand = options.dev ? 'node bin' : 'underpost';
-      const message = shellExec(`node bin cmt --changelog --changelog-no-hash`, { silent: true, stdout: true }).trim();
-      shellExec(`${baseCommand} run clean`);
+      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`);
+
+      // Capture last N commit messages for propagation.
+      // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
+      const fromN =
+        options.fromNCommit && parseInt(options.fromNCommit) > 0
+          ? parseInt(options.fromNCommit)
+          : Underpost.repo.getUnpushedCount('.').count;
+      const message = shellExec(`node bin cmt --changelog ${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');
+
+      const sanitizedMessage = Underpost.repo.sanitizeChangelogMessage(message);
+
+      // Push engine repo so workflow YAML changes reach GitHub
       shellExec(`git reset`);
-      function replaceNthNewline(str, n, replacement = ' ') {
-        let count = 0;
-        return str.replace(/\r\n?|\n/g, (match) => {
-          count++;
-          return count === n ? replacement : match;
-        });
-      }
-      shellExec(
-        `${baseCommand} cmt . --empty ci package-pwa-microservices-template${
-          path.startsWith('sync') ? `-${path}` : ''
-        }${
-          message
-            ? ` "${replaceNthNewline(
-                message.replaceAll('"', '').replaceAll('`', '').replaceAll('#', '').replaceAll('- ', ''),
-                2,
-              )}"`
-            : ''
-        }`,
-      );
       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';
+      }
+
+      // 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;
+
+      Underpost.repo.dispatchWorkflow({
+        repo,
+        workflowFile: 'npmpkg.ci.yml',
+        ref: 'master',
+        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 {Object} 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`);
+
+      // Capture last N commit messages from the engine repo.
+      // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
+      const fromN =
+        options.fromNCommit && parseInt(options.fromNCommit) > 0
+          ? parseInt(options.fromNCommit)
+          : Underpost.repo.getUnpushedCount('.').count;
+      const rawMessage = shellExec(`node bin cmt --changelog ${fromN} --changelog-no-hash`, {
+        silent: true,
+        stdout: true,
+      }).trim();
+      const sanitizedMessage = Underpost.repo.sanitizeChangelogMessage(rawMessage);
+
+      const { triggerCmd } = path
+        ? await Underpost.release.ci(path, sanitizedMessage, options)
+        : await Underpost.release.pwa(sanitizedMessage, options);
+      pbcopy(triggerCmd + ' && cd /home/dd/engine');
+    },
     /**
      * @method template-deploy-image
-     * @description Commits and pushes a Docker image deployment for the `engine` repository.
+     * @description Dispatches the Docker image CI workflow for the `engine` repository.
      * @param {string} path - The input value, identifier, or path for the operation.
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'template-deploy-image': (path, options = DEFAULT_OPTION) => {
-      // const baseCommand = options.dev ? 'node bin' : 'underpost';
-      shellExec(
-        `cd /home/dd/engine && git reset && underpost cmt . --empty ci docker-image 'underpost-engine:${
-          Underpost.version
-        }' && underpost push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`,
-      );
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: 'docker-image.ci.yml',
+        ref: 'master',
+        inputs: {},
+      });
+    },
+    /**
+     * @method docker-image
+     * @description Dispatches the Docker image CI workflow (`docker-image.ci.yml`) for the `engine` repository via `workflow_dispatch`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'docker-image': (path, options = DEFAULT_OPTION) => {
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: 'docker-image.ci.yml',
+        ref: 'master',
+        inputs: {},
+      });
     },
     /**
      * @method clean
@@ -467,18 +579,30 @@ class UnderpostRun {
     },
     /**
      * @method ssh-deploy
-     * @description Performs a Git reset, commits with a message `cd ssh-${path}`, and pushes the `engine` repository, likely triggering an SSH-based CD pipeline.
-     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment identifier for the commit message).
+     * @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 {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'ssh-deploy': (path, options = DEFAULT_OPTION) => {
       actionInitLog();
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      shellCd('/home/dd/engine');
-      shellExec(`git reset`);
-      shellExec(`${baseCommand} cmt . --empty cd ssh-${path}`);
-      shellExec(`${baseCommand} push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`);
+
+      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-/, '');
+      }
+
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: `${confId}.cd.yml`,
+        ref: 'master',
+        inputs: { job },
+      });
     },
     /**
      * @method ide
@@ -488,15 +612,25 @@ class UnderpostRun {
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    ide: (path, options = DEFAULT_OPTION) => {
-      const { underpostRoot } = options;
-      if (path === 'install') {
-        shellExec(`sudo curl -f https://zed.dev/install.sh | sh`);
-        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(`node ${underpostRoot}/bin/zed ${path}`);
+    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
@@ -520,12 +654,13 @@ class UnderpostRun {
       const env = options.dev ? 'development' : 'production';
       const baseCommand = 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.dev || !isDeployRunnerContext(path, options) ? 'kind-control-plane' : os.hostname(),
+        !options.kubeadm && !options.k3s ? 'kind-control-plane' : os.hostname(),
       ];
       let [deployId, replicas, versions, image, node] = path ? path.split(',') : defaultPath;
       deployId = deployId ? deployId : defaultPath[0];
@@ -540,7 +675,8 @@ class UnderpostRun {
           if (!validVersion) throw new Error('Version mismatch');
         }
         if (options.timezone !== 'none') shellExec(`${baseCommand} run${baseClusterCommand} tz`);
-        if (options.deployIdCronJobs !== 'none') shellExec(`node bin cron --dev --setup-start --apply`);
+        if (options.deployIdCronJobs !== 'none')
+          shellExec(`node bin cron${baseClusterCommand}${clusterFlag} --setup-start --git --apply`);
       }
 
       const currentTraffic = isDeployRunnerContext(path, options)
@@ -553,20 +689,25 @@ class UnderpostRun {
       const cmdString = options.cmd
         ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
         : '';
+      const gitCleanFlag = options.gitClean ? ' --git-clean' : '';
 
       shellExec(
-        `${baseCommand} deploy --kubeadm --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
+        `${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} dd ${env}`,
+        }${timeoutFlags}${cmdString}${gitCleanFlag} ${deployId} ${env}`,
       );
 
       if (isDeployRunnerContext(path, options)) {
+        // Backup app/services repositories with repo-backup configured
         shellExec(
-          `${baseCommand} deploy --kubeadm${cmdString} --replicas ${replicas} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
+          `${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} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
             options.namespace ? ` --namespace ${options.namespace}` : ''
-          }${timeoutFlags}`,
+          }${timeoutFlags}${gitCleanFlag}`,
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
@@ -778,6 +919,7 @@ class UnderpostRun {
       const confInstances = JSON.parse(
         fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
       );
+      let promotedTraffic = '';
       for (const instance of confInstances) {
         let {
           id: _id,
@@ -797,6 +939,7 @@ class UnderpostRun {
           namespace: options.namespace,
         });
         const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
+        promotedTraffic = targetTraffic;
         let proxyYaml =
           Underpost.deploy.baseProxyYamlFactory({ host: _host, env: options.tls ? 'production' : env, options }) +
           Underpost.deploy.deploymentYamlServiceFactory({
@@ -822,6 +965,18 @@ 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}`);
+      }
     },
 
     /**
@@ -861,12 +1016,12 @@ EOF
         // `localhost/rockylinux9-underpost:${Underpost.version}`
         if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
 
-        if (options.nodeName) {
-          shellExec(`sudo crictl pull ${_image}`);
-        } else {
-          shellExec(`docker pull ${_image}`);
-          shellExec(`sudo kind load docker-image ${_image}`);
-        }
+        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,
@@ -875,7 +1030,7 @@ EOF
 
         const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
         const podId = `${_deployId}-${env}-${targetTraffic}`;
-        const ignorePods = Underpost.deploy.get(podId, 'pods', options.namespace).map((p) => p.NAME);
+        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`);
@@ -887,7 +1042,30 @@ EOF
               env,
               version: targetTraffic,
               nodeName: options.nodeName,
+              clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
+              gitClean: options.gitClean || false,
             });
+        // 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`,
+          ),
+        );
+
         let deploymentYaml = `---
 ${Underpost.deploy
   .deploymentYamlPartsFactory({
@@ -899,7 +1077,7 @@ ${Underpost.deploy
     image: _image,
     namespace: options.namespace,
     volumes: _volumes,
-    cmd: _cmd[env],
+    cmd: resolvedCmd,
   })
   .replace('{{ports}}', buildKindPorts(_fromPort, _toPort))}
 `;
@@ -945,7 +1123,7 @@ EOF
      * @memberof UnderpostRun
      */
     'ls-deployments': async (path, options = DEFAULT_OPTION) => {
-      console.table(await Underpost.deploy.get(path, 'deployments', options.namespace));
+      console.table(await Underpost.kubectl.get(path, 'deployments', options.namespace));
     },
 
     /**
@@ -1008,9 +1186,7 @@ EOF
         volumeMountPath: volumeHostPath,
         ...(options.dev ? { volumeHostPath } : { claimName }),
         on: {
-          init: async () => {
-            // openTerminal(`kubectl logs -f ${podName}`);
-          },
+          init: async () => {},
         },
         args: [daemonProcess(path ? path : `cd /home/dd/engine && npm install && npm run test`)],
       };
@@ -1041,15 +1217,13 @@ EOF
     'db-client': async (path, options = DEFAULT_OPTION) => {
       const { underpostRoot } = options;
 
-      const image = 'adminer:4.7.6-standalone';
-
-      if (!options.kubeadm && !options.k3s) {
-        // Only load if not kubeadm/k3s (Kind needs it)
-        shellExec(`docker pull ${image}`);
-        shellExec(`sudo kind load docker-image ${image}`);
-      } else if (options.kubeadm || options.k3s)
-        // For kubeadm/k3s, ensure it's available for containerd
-        shellExec(`sudo crictl pull ${image}`);
+      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}`);
@@ -1145,7 +1319,7 @@ EOF
       const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
       let hosts = [];
       for (const deployId of deployList) {
-        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+        const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
         hosts = hosts.concat(Object.keys(confServer));
       }
       shellExec(`node bin cluster --prom ${hosts.join(',')}`);
@@ -1318,34 +1492,31 @@ EOF
       if (!subConf) subConf = 'local';
       if (options.reset && fs.existsSync(`./engine-private/conf/${deployId}`))
         fs.removeSync(`./engine-private/conf/${deployId}`);
-      if (!fs.existsSync(`./engine-private/conf/${deployId}`)) Config.deployIdFactory(deployId, { subConf });
       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}${
+        const cmd = `npm run dev:api ${deployId} ${subConf} ${host} ${_path} ${clientHostPort} proxy${
           options.tls ? ' tls' : ''
         }`;
-        options.terminal ? openTerminal(cmd) : shellExec(cmd, { async: true });
+        shellExec(cmd, { async: true });
       }
       await awaitDeployMonitor(true);
       {
-        const cmd = `npm run dev-client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
-        options.terminal
-          ? openTerminal(cmd)
-          : shellExec(cmd, {
-              async: true,
-            });
+        const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
+
+        shellExec(cmd, {
+          async: true,
+        });
       }
       await awaitDeployMonitor(true);
       shellExec(
-        `./node_modules/.bin/env-cmd -f .env.development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${
-          options.tls ? ' tls' : ''
-        }`,
+        `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
       );
     },
 
@@ -1364,7 +1535,7 @@ EOF
       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 = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.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`)
@@ -1455,9 +1626,7 @@ EOF
     'etc-hosts': async (path = '', options = DEFAULT_OPTION) => {
       const hosts = path ? path.split(',') : [];
       if (options.deployId) {
-        const confServer = JSON.parse(
-          fs.readFileSync(`./engine-private/conf/${options.deployId}/conf.server.json`, 'utf8'),
-        );
+        const confServer = loadConfServerJson(`./engine-private/conf/${options.deployId}/conf.server.json`);
         hosts.push(...Object.keys(confServer));
       }
       const hostListenResult = Underpost.deploy.etcHostFactory(hosts);
@@ -1527,29 +1696,75 @@ EOF
     },
 
     /**
-     * @method ptls
-     * @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).
+     * @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 {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    ptls: async (path = '', options = DEFAULT_OPTION) => {
-      shellExec(`chmod +x ${options.underpostRoot}/scripts/ports-ls.sh`);
-      shellExec(`${options.underpostRoot}/scripts/ports-ls.sh`);
+    '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 {Object} 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 release-cmt
-     * @description Commits and pushes a new release for the `engine` repository with a message indicating the new version.
-     * @param {string} path - The input value, identifier, or path for the operation.
+     * @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 {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    'release-cmt': async (path, options = DEFAULT_OPTION) => {
-      shellExec(`underpost run pull`);
-      shellExec(`underpost run secret`);
-      shellCd(`/home/dd/engine`);
-      shellExec(`underpost cmt --empty . ci engine ' New engine release $(underpost --version)'`);
-      shellExec(`underpost push . ${process.env.GITHUB_USERNAME}/engine`, { silent: true });
+    ports: async (path = '', options = DEFAULT_OPTION) => {
+      shellExec(`chmod +x ${options.underpostRoot}/scripts/ports-ls.sh`);
+      shellExec(`${options.underpostRoot}/scripts/ports-ls.sh`);
     },
 
     /**
@@ -1571,43 +1786,12 @@ EOF
         : [
             `npm install -g npm@11.2.0`,
             `npm install -g underpost`,
-            `${baseCommand} secret underpost --create-from-file /etc/config/.env.${env}`,
-            `${baseCommand} start --build --run ${deployId} ${env} --underpost-quickly-install`,
+            `${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 sync-replica
-     * @description Syncs a replica for the dd.router
-     * @param {string} path - The input value, identifier, or path for the operation.
-     * @param {Object} options - The default underpost runner options for customizing workflow
-     * @memberof UnderpostRun
-     */
-    'sync-replica': async (path, options = DEFAULT_OPTION) => {
-      const env = options.dev ? 'development' : 'production';
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-
-      for (let deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
-        deployId = deployId.trim();
-        const _path = '/single-replica';
-        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
-        shellExec(`${baseCommand} env ${deployId} ${env}`);
-        for (const host of Object.keys(confServer))
-          if (_path in confServer[host]) shellExec(`node bin/deploy build-single-replica ${deployId} ${host} ${_path}`);
-        const node = options.nodeName
-          ? options.nodeName
-          : options.dev || !isDeployRunnerContext(path, options)
-            ? 'kind-control-plane'
-            : os.hostname();
-        // deployId, replicas, versions, image, node
-        let defaultPath = [deployId, 1, ``, ``, node];
-        shellExec(`${baseCommand} run${options.dev === true ? ' --dev' : ''} --build sync ${defaultPath}`);
-        shellExec(`node bin/deploy build-full-client ${deployId}`);
-      }
-      if (isDeployRunnerContext(path, options)) shellExec(`${baseCommand} run promote ${path} production`);
-    },
-
     /**
      * @method tf-vae-test
      * @description Creates and runs a job pod (`tf-vae-test`) that installs TensorFlow dependencies, clones the TensorFlow docs, and runs the CVAE tutorial script, with a terminal monitor attached.
@@ -1633,7 +1817,7 @@ EOF
 
               const { close } = await (async () => {
                 const checkAwaitPath = '/await';
-                while (!Underpost.deploy.existsContainerFile({ podName, path: checkAwaitPath })) {
+                while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
                   logger.info('monitor', checkAwaitPath);
                   await timer(1000);
                 }
@@ -1660,7 +1844,7 @@ EOF
                 logger.info('monitor', checkPath);
                 {
                   const checkAwaitPath = `/home/dd/docs${checkPath}`;
-                  while (!Underpost.deploy.existsContainerFile({ podName, path: checkAwaitPath })) {
+                  while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
                     logger.info('waiting for', checkAwaitPath);
                     await timer(1000);
                   }
@@ -1680,7 +1864,7 @@ EOF
                   shellExec(`sudo kubectl cp ${nameSpace}/${podName}:${basePath}/docs${fromPath} ${toPath}`);
                 }
 
-                openTerminal(`firefox ${outsPaths.join(' ')}`, { single: true });
+                shellExec(`firefox ${outsPaths.join(' ')}`);
                 process.exit(0);
               }
             })();
@@ -1726,7 +1910,8 @@ EOF
 
       shellCd(dir);
 
-      shellExec(`git init && git add . && git commit -m "Base implementation"`);
+      Underpost.repo.initLocalRepo({ path: dir });
+      shellExec(`git add . && git commit -m "Base implementation"`);
       shellExec(`chmod +x ./replace_params.sh`);
       shellExec(`chmod +x ./build.sh`);
 
@@ -1771,11 +1956,46 @@ EOF
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
+    /**
+     * @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 {Object} 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);
+    },
+
     secret: (path, options = DEFAULT_OPTION) => {
       const secretPath = path ? path : `/home/dd/engine/engine-private/conf/dd-cron/.env.production`;
-      const command = options.dev
-        ? `node bin secret underpost --create-from-file ${secretPath}`
-        : `underpost secret underpost --create-from-file ${secretPath}`;
+      const command = `node bin secret underpost --create-from-file ${secretPath}`;
       shellExec(command);
     },
     /**