underpost 3.1.3 → 3.2.0

package/src/cli/deploy.js

@@ -155,6 +155,7 @@ metadata:
   namespace: ${namespace ? namespace : 'default'}
   labels:
     app: ${deployId}-${env}-${suffix}
+    deploy-id: ${deployId}-${env}
 spec:
   replicas: ${replicas}
   selector:
@@ -164,6 +165,7 @@ spec:
     metadata:
       labels:
         app: ${deployId}-${env}-${suffix}
+        deploy-id: ${deployId}-${env}
     spec:
       containers:
         - name: ${deployId}-${env}-${suffix}
@@ -260,6 +262,14 @@ ${Underpost.deploy
         }
         fs.writeFileSync(`./engine-private/conf/${deployId}/build/${env}/deployment.yaml`, deploymentYamlParts, 'utf8');
 
+        Underpost.deploy.buildGrpcServiceManifest({
+          deployId,
+          env,
+          confServer,
+          namespace: options.namespace,
+          traffic: options.traffic && typeof options.traffic === 'string' ? options.traffic.split(',') : ['blue'],
+        });
+
         const confVolume = fs.existsSync(`./engine-private/conf/${deployId}/conf.volume.json`)
           ? JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.volume.json`, 'utf8'))
           : [];
@@ -369,6 +379,67 @@ ${Underpost.deploy
         }
       }
     },
+    /**
+     * Builds and writes a gRPC ClusterIP service YAML for a deployment.
+     * Scans conf.server.json for gRPC ports and emits grpc-service.yaml under
+     * `engine-private/conf/<deployId>/build/<env>/`. The selector always uses the
+     * explicit `app: <deployId>-<env>-<traffic>` label to target only the active
+     * colour (blue or green).
+     * @param {string} deployId - Deployment ID.
+     * @param {string} env - Environment ('development' or 'production').
+     * @param {object} confServer - Parsed conf.server.json content.
+     * @param {string} [namespace='default'] - Kubernetes namespace.
+     * @param {string[]} [traffic=['blue']] - Active traffic colour(s) ('blue', 'green', or both).
+     * @param {string|null} [host=null] - Specific host to scan for gRPC ports. If null, all hosts are scanned.
+     * @returns {string|null} - Path to the written YAML file, or null if no gRPC ports found.
+     * @memberof UnderpostDeploy
+     */
+    buildGrpcServiceManifest({ deployId, env, confServer, namespace = 'default', traffic = ['blue'], host = null }) {
+      const grpcPorts = new Set();
+      const hostsToScan = host ? [host] : Object.keys(confServer);
+      for (const h of hostsToScan) {
+        if (!confServer[h]) continue;
+        for (const path of Object.keys(confServer[h])) {
+          const grpc = confServer[h][path].grpc;
+          if (grpc && grpc.port) grpcPorts.add(parseInt(grpc.port));
+        }
+      }
+      if (grpcPorts.size === 0) return null;
+      const grpcPortsList = [...grpcPorts]
+        .map(
+          (port) => `    - name: grpc-${port}
+      protocol: TCP
+      port: ${port}
+      targetPort: ${port}`,
+        )
+        .join('\n');
+      let grpcServiceYaml = '';
+      for (const color of traffic) {
+        const grpcServiceName = `${deployId}-grpc-service-${env}-${color}`;
+        const selectorYaml = `app: ${deployId}-${env}-${color}`;
+        grpcServiceYaml += `---
+apiVersion: v1
+kind: Service
+metadata:
+  name: ${grpcServiceName}
+  namespace: ${namespace}
+  labels:
+    app: ${grpcServiceName}
+spec:
+  type: ClusterIP
+  selector:
+    ${selectorYaml}
+  ports:
+${grpcPortsList}
+`;
+        logger.info(
+          `gRPC ClusterIP service YAML written: ${grpcServiceName} (selector: ${selectorYaml}, ports: ${[...grpcPorts].join(', ')})`,
+        );
+      }
+      const yamlPath = `./engine-private/conf/${deployId}/build/${env}/grpc-service.yaml`;
+      fs.writeFileSync(yamlPath, grpcServiceYaml, 'utf8');
+      return yamlPath;
+    },
     /**
      * Builds a Certificate resource for a host using cert-manager.
      * @param {string} host - Hostname for which the certificate is being built.
@@ -478,6 +549,10 @@ spec:
      * @param {string} [options.kindType] - Type of Kubernetes resource to retrieve information for.
      * @param {number} [options.port] - Port number for exposing the deployment.
      * @param {string} [options.cmd] - Custom initialization command for deploymentYamlPartsFactory (comma-separated commands).
+     * @param {boolean} [options.k3s] - Whether to use k3s cluster context.
+     * @param {boolean} [options.kubeadm] - Whether to use kubeadm cluster context.
+     * @param {boolean} [options.kind] - Whether to use kind cluster context.
+     * @param {boolean} [options.gitClean] - Whether to run git clean on volume mount paths before copying.
      * @returns {Promise<void>} - Promise that resolves when the deployment process is complete.
      * @memberof UnderpostDeploy
      */
@@ -515,6 +590,10 @@ spec:
         port: 0,
         exposePort: 0,
         cmd: '',
+        k3s: false,
+        kubeadm: false,
+        kind: false,
+        gitClean: false,
       },
     ) {
       const namespace = options.namespace ? options.namespace : 'default';
@@ -553,7 +632,7 @@ EOF`);
             env,
             traffic: Underpost.deploy.getCurrentTraffic(deployId, { namespace }),
             router: await Underpost.deploy.routerFactory(deployId, env),
-            pods: await Underpost.deploy.get(deployId),
+            pods: await Underpost.kubectl.get(deployId),
             instances,
           });
         }
@@ -595,7 +674,7 @@ EOF`);
         if (!deployId) continue;
         if (options.expose === true) {
           const kindType = options.kindType ? options.kindType : 'svc';
-          const svc = Underpost.deploy.get(deployId, kindType)[0];
+          const svc = Underpost.kubectl.get(deployId, kindType)[0];
           const port = options.exposePort
             ? parseInt(options.exposePort)
             : options.port
@@ -634,6 +713,8 @@ EOF`);
                   version,
                   namespace,
                   nodeName: options.node ? options.node : env === 'development' ? 'kind-worker' : os.hostname(),
+                  clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
+                  gitClean: options.gitClean || false,
                 });
           }
 
@@ -652,8 +733,11 @@ EOF`);
             : `manifests/deployment/${deployId}-${env}`;
 
         if (!options.remove) {
-          if (!options.disableUpdateDeployment)
+          if (!options.disableUpdateDeployment) {
             shellExec(`sudo kubectl apply -f ./${manifestsPath}/deployment.yaml -n ${namespace}`);
+            const grpcServicePath = `./${manifestsPath}/grpc-service.yaml`;
+            if (fs.existsSync(grpcServicePath)) shellExec(`sudo kubectl apply -f ${grpcServicePath} -n ${namespace}`);
+          }
           if (!options.disableUpdateProxy)
             shellExec(`sudo kubectl apply -f ./${manifestsPath}/proxy.yaml -n ${namespace}`);
 
@@ -671,65 +755,6 @@ EOF`);
 ` + renderHosts,
         );
     },
-    /**
-     * Retrieves information about a deployment.
-     * @param {string} deployId - Deployment ID for which information is being retrieved.
-     * @param {string} kindType - Type of Kubernetes resource to retrieve information for (e.g. 'pods').
-     * @param {string} namespace - Kubernetes namespace to retrieve information from.
-     * @returns {Array<object>} - Array of objects containing information about the deployment.
-     * @memberof UnderpostDeploy
-     */
-    get(deployId, kindType = 'pods', namespace = '') {
-      const raw = shellExec(
-        `sudo kubectl get ${kindType}${namespace ? ` -n ${namespace}` : ` --all-namespaces`} -o wide`,
-        {
-          stdout: true,
-          disableLog: true,
-          silent: true,
-        },
-      );
-
-      const heads = raw
-        .split(`\n`)[0]
-        .split(' ')
-        .filter((_r) => _r.trim());
-
-      const pods = raw
-        .split(`\n`)
-        .filter((r) => (deployId ? r.match(deployId) : r.trim() && !r.match('NAME')))
-        .map((r) => r.split(' ').filter((_r) => _r.trim()));
-
-      const result = [];
-
-      for (const row of pods) {
-        const pod = {};
-        let index = -1;
-        for (const head of heads) {
-          index++;
-          pod[head] = row[index];
-        }
-        result.push(pod);
-      }
-
-      return result;
-    },
-
-    /**
-     * Checks if a container file exists in a pod.
-     * @param {object} options - Options for the check.
-     * @param {string} options.podName - Name of the pod to check.
-     * @param {string} options.path - Path to the container file to check.
-     * @returns {boolean} - True if the container file exists, false otherwise.
-     * @memberof UnderpostDeploy
-     */
-    existsContainerFile({ podName, path }) {
-      const result = shellExec(`kubectl exec ${podName} -- test -f ${path} && echo "true" || echo "false"`, {
-        stdout: true,
-        disableLog: true,
-        silent: true,
-      }).trim();
-      return result === 'true';
-    },
     /**
      * Checks the status of a deployment.
      * @param {string} deployId - Deployment ID for which the status is being checked.
@@ -742,7 +767,7 @@ EOF`);
      */
     async checkDeploymentReadyStatus(deployId, env, traffic, ignoresNames = [], namespace = 'default') {
       const cmd = `underpost config get container-status`;
-      const pods = Underpost.deploy.get(`${deployId}-${env}-${traffic}`, 'pods', namespace);
+      const pods = Underpost.kubectl.get(`${deployId}-${env}-${traffic}`, 'pods', namespace);
       const readyPods = [];
       const notReadyPods = [];
       for (const pod of pods) {
@@ -814,6 +839,9 @@ EOF`);
 
       shellExec(`sudo kubectl apply -f ./engine-private/conf/${deployId}/build/${env}/proxy.yaml -n ${namespace}`);
 
+      const grpcServicePath = `./engine-private/conf/${deployId}/build/${env}/grpc-service.yaml`;
+      if (fs.existsSync(grpcServicePath)) shellExec(`kubectl apply -f ${grpcServicePath} -n ${namespace}`);
+
       Underpost.env.set(`${deployId}-${env}-traffic`, targetTraffic);
     },
 
@@ -829,6 +857,8 @@ EOF`);
      * @param {string} options.version - Version of the deployment.
      * @param {string} options.namespace - Kubernetes namespace for the deployment.
      * @param {string} options.nodeName - Node name for the deployment.
+     * @param {string} [options.clusterContext='kind'] - Cluster context type ('kind', 'kubeadm', or 'k3s').
+     * @param {boolean} [options.gitClean=false] - Whether to run git clean on volumeMountPath before copying.
      * @memberof UnderpostDeploy
      */
     deployVolume(
@@ -839,6 +869,8 @@ EOF`);
         version: '',
         namespace: '',
         nodeName: '',
+        clusterContext: 'kind',
+        gitClean: false,
       },
     ) {
       if (!volume.claimName) {
@@ -846,19 +878,26 @@ EOF`);
         return;
       }
       const { deployId, env, version, namespace } = options;
+      const clusterContext = options.clusterContext || 'kind';
       const pvcId = `${volume.claimName}-${deployId}-${env}-${version}`;
       const pvId = `${volume.claimName.replace('pvc-', 'pv-')}-${deployId}-${env}-${version}`;
       const rootVolumeHostPath = `/home/dd/engine/volume/${pvId}`;
+      if (options.gitClean && volume.volumeMountPath) {
+        Underpost.repo.clean({ paths: [volume.volumeMountPath] });
+      }
       if (options.nodeName) {
         if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
         fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
-      } else {
+      } else if (clusterContext === 'kind') {
         shellExec(`docker exec -i kind-worker bash -c "mkdir -p ${rootVolumeHostPath}"`);
         // shellExec(`docker cp ${volume.volumeMountPath} kind-worker:${rootVolumeHostPath}`);
         shellExec(`tar -C ${volume.volumeMountPath} -c . | docker cp - kind-worker:${rootVolumeHostPath}`);
         shellExec(
           `docker exec -i kind-worker bash -c "chown -R 1000:1000 ${rootVolumeHostPath}; chmod -R 755 ${rootVolumeHostPath}"`,
         );
+      } else {
+        if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
+        fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
       }
       shellExec(`kubectl delete pvc ${pvcId} -n ${namespace} --ignore-not-found`);
       shellExec(`kubectl delete pv ${pvId} --ignore-not-found`);
@@ -1041,7 +1080,7 @@ ${renderHosts}`,
     async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default', outLogType = '') {
       let checkStatusIteration = 0;
       const checkStatusIterationMsDelay = 1000;
-      const maxIterations = 500;
+      const maxIterations = 3000;
       const deploymentId = `${deployId}-${env}-${targetTraffic}`;
       const iteratorTag = `[${deploymentId}]`;
       logger.info('Deployment init', { deployId, env, targetTraffic, checkStatusIterationMsDelay, namespace });

package/src/cli/env.js

@@ -48,6 +48,7 @@ class UnderpostRootEnv {
         return;
       }
       const exeRootPath = `${getNpmRootPath()}/underpost`;
+      fs.ensureDirSync(exeRootPath);
       const envPath = `${exeRootPath}/.env`;
       _set(envPath, key, value);
     },

package/src/cli/fs.js

@@ -107,7 +107,8 @@ class UnderpostFileStorage {
             await Underpost.fs.pull(_path, options);
           } else logger.warn(`Pull path already exists`, _path);
         }
-        shellExec(`cd ${path} && git init && git add . && git commit -m "Base pull state"`);
+        Underpost.repo.initLocalRepo({ path });
+        shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`);
       } else {
         const files =
           options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });

package/src/cli/index.js

@@ -87,7 +87,7 @@ program
   .argument(`[commit-type]`, `The type of commit to perform. Options: ${Object.keys(commitData).join(', ')}.`)
   .argument(`[module-tag]`, 'Optional: Sets a specific module tag for the commit.')
   .argument(`[message]`, 'Optional: Provides an additional custom message for the commit.')
-  .option(`--log <latest-n>`, 'Shows commit history from the specified number of latest n path commits.')
+  .option(`--log [latest-n]`, 'Shows commit history from the specified number of latest n path commits.')
   .option('--last-msg <latest-n>', 'Displays the last n commit message.')
   .option('--empty', 'Allows committing with empty files.')
   .option('--copy', 'Copies the generated commit message to the clipboard.')
@@ -108,7 +108,14 @@ program
     '--changelog-no-hash',
     'Excludes commit hashes from the generated changelog entries (used with --changelog-build).',
   )
+  .option('--unpush', 'With --log, automatically sets range to unpushed commits ahead of remote.')
   .option('-b', 'Shows the current Git branch name.')
+  .option('-p [branch]', 'Shows the reflog for the specified branch.')
+  .option('--bc <commit-hash>', 'Shows branches that contain the specified commit.')
+  .option(
+    '--is-remote-repo <url-repo>',
+    'Checks whether a remote Git repository URL is reachable. Prints true or false.',
+  )
   .description('Manages commits to a GitHub repository, supporting various commit types and options.')
   .action(Underpost.repo.commit);
 
@@ -308,6 +315,9 @@ program
     'Retrieves current network traffic data from resource deployments and the host machine network configuration.',
   )
   .option('--kubeadm', 'Enables the kubeadm context for deployment operations.')
+  .option('--k3s', 'Enables the k3s context for deployment operations.')
+  .option('--kind', 'Enables the kind context for deployment operations.')
+  .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
   .option('--etc-hosts', 'Enables the etc-hosts context for deployment operations.')
   .option('--restore-hosts', 'Restores default `/etc/hosts` entries.')
   .option('--disable-update-underpost-config', 'Disables updates to Underpost configuration during deployment.')
@@ -597,6 +607,7 @@ program
   .option('--kubeadm', 'Sets the kubeadm cluster context for the runner execution.')
   .option('--k3s', 'Sets the k3s cluster context for the runner execution.')
   .option('--kind', 'Sets the kind cluster context for the runner execution.')
+  .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
   .option('--log-type <log-type>', 'Sets the log type for the runner execution.')
   .option('--deploy-id <deploy-id>', 'Sets deploy id context for the runner execution.')
   .option('--user <user>', 'Sets user context for the runner execution.')
@@ -640,6 +651,7 @@ program
       'Format: semicolon-separated entries of "ip=hostname1,hostname2" ' +
       '(e.g., "127.0.0.1=foo.local,bar.local;10.1.2.3=foo.remote,bar.remote").',
   )
+  .option('--copy', 'Copies the runner output to the clipboard (supported by: generate-pass, template-deploy-local).')
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
@@ -764,4 +776,33 @@ program
   )
   .action(Underpost.baremetal.callback);
 
+program
+  .command('release')
+  .argument('[version]', 'The new version string to set (e.g., "3.1.4"). Defaults to current version.')
+  .option('--build', 'Builds a new version: tests template, bumps versions, rebuilds manifests and configs.')
+  .option('--deploy', 'Deploys the release: syncs secrets, commits, and pushes to remote repositories.')
+  .option(
+    '--ci-push <deploy-id>',
+    'Local equivalent of engine-*.ci.yml: builds dd-{deploy-id} and pushes to the engine-{deploy-id} repository. ' +
+      'Accepts the suffix (e.g., "cyberia"), "dd-cyberia", or "engine-cyberia".',
+  )
+  .option(
+    '--message <message>',
+    'Commit message for --ci-push or --pwa-build (defaults to last commit of the engine repository).',
+  )
+  .option(
+    '--pwa-build',
+    'Runs the pwa-microservices-template update flow: always re-clones, syncs engine sources, installs, builds, and pushes.',
+  )
+  .description('Release orchestrator for building new versions and deploying releases of the Underpost CLI.')
+  .action(async (version, options) => {
+    if (options.build) return Underpost.release.build(version, options);
+    if (options.deploy) return Underpost.release.deploy(version, options);
+    if (options.ciPush) return Underpost.release.ci(options.ciPush, options.message, options);
+    if (options.pwaBuild) return Underpost.release.pwa(options.message, options);
+    console.log(
+      'Please specify --build, --deploy, --ci-push, or --pwa-build. Use "underpost release --help" for details.',
+    );
+  });
+
 export { program };

package/src/cli/kubectl.js

@@ -0,0 +1,211 @@
+/**
+ * Kubectl module providing low-level Kubernetes resource management primitives.
+ * Centralises pod querying, file transfer, and in-container execution operations
+ * that were previously scattered across db, deploy, and cluster modules.
+ * @module src/cli/kubectl.js
+ * @namespace UnderpostKubectl
+ */
+
+import { loggerFactory } from '../server/logger.js';
+import { shellExec } from '../server/process.js';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Redacts credentials from shell command strings before logging.
+ * Masks passwords in `-p<password>`, `--password=<password>`, and `-P <password>` patterns.
+ * @param {string} cmd - The raw command string.
+ * @returns {string} The command with credentials replaced by `***`.
+ * @memberof UnderpostKubectl
+ */
+const sanitizeCommand = (cmd) => {
+  if (typeof cmd !== 'string') return cmd;
+  return cmd
+    .replace(/-p['"]?[^\s'"]+/g, '-p***')
+    .replace(/--password=['"]?[^\s'"]+/g, '--password=***')
+    .replace(/-P\s+['"]?[^\s'"]+/g, '-P ***');
+};
+
+/**
+ * @class UnderpostKubectl
+ * @description Kubernetes cluster resource management primitives.
+ * Provides a unified interface for kubectl operations: resource listing, in-pod
+ * command execution, file transfer, and pod discovery/filtering.
+ * All methods are stateless and safe to call from any other CLI module.
+ * @memberof UnderpostKubectl
+ */
+class UnderpostKubectl {
+  static API = {
+    /**
+     * Lists Kubernetes resources matching `deployId`, parsed into plain objects.
+     * Equivalent to `kubectl get <kindType> -o wide`, filtered by name substring.
+     * @param {string} deployId - Substring to match against resource names. Empty string returns all.
+     * @param {string} [kindType='pods'] - Resource kind: pods, deployments, svc, nodes, …
+     * @param {string} [namespace=''] - Namespace to query; empty string → --all-namespaces.
+     * @returns {Array<object>} Parsed rows keyed by column header (NAME, STATUS, NODE, …).
+     * @memberof UnderpostKubectl
+     */
+    get(deployId, kindType = 'pods', namespace = '') {
+      const raw = shellExec(
+        `sudo kubectl get ${kindType}${namespace ? ` -n ${namespace}` : ` --all-namespaces`} -o wide`,
+        { stdout: true, disableLog: true, silent: true },
+      );
+
+      const heads = raw
+        .split(`\n`)[0]
+        .split(' ')
+        .filter((_r) => _r.trim());
+
+      const pods = raw
+        .split(`\n`)
+        .filter((r) => (deployId ? r.match(deployId) : r.trim() && !r.match('NAME')))
+        .map((r) => r.split(' ').filter((_r) => _r.trim()));
+
+      const result = [];
+      for (const row of pods) {
+        const pod = {};
+        let index = -1;
+        for (const head of heads) {
+          index++;
+          pod[head] = row[index];
+        }
+        result.push(pod);
+      }
+      return result;
+    },
+
+    /**
+     * Executes a kubectl command with credential-safe logging and error propagation.
+     * @param {string} command - Full kubectl command string.
+     * @param {object} [options={}] - Execution options.
+     * @param {string} [options.context=''] - Human-readable label for log messages.
+     * @returns {string} stdout output from the command.
+     * @throws {Error} Re-throws any execution error after logging.
+     * @memberof UnderpostKubectl
+     */
+    run(command, options = {}) {
+      const { context = '' } = options;
+      try {
+        logger.info(`Executing kubectl command`, { command: sanitizeCommand(command), context });
+        return shellExec(command, { stdout: true, disableLog: true });
+      } catch (error) {
+        logger.error(`kubectl command failed`, { command: sanitizeCommand(command), error: error.message, context });
+        throw error;
+      }
+    },
+
+    /**
+     * Runs a shell command inside a pod container via `kubectl exec`.
+     * @param {object} params
+     * @param {string} params.podName - Target pod name.
+     * @param {string} params.namespace - Pod namespace.
+     * @param {string} params.command - Shell command to run inside the container.
+     * @returns {string} stdout output from the in-pod command.
+     * @throws {Error} Re-throws any execution error after logging.
+     * @memberof UnderpostKubectl
+     */
+    exec({ podName, namespace, command }) {
+      try {
+        const kubectlCmd = `sudo kubectl exec -n ${namespace} -i ${podName} -- sh -c "${command}"`;
+        return Underpost.kubectl.run(kubectlCmd, { context: `exec in pod ${podName}` });
+      } catch (error) {
+        logger.error('Failed to execute command in pod', {
+          podName,
+          command: sanitizeCommand(command),
+          error: error.message,
+        });
+        throw error;
+      }
+    },
+
+    /**
+     * Copies a local file into a pod via `kubectl cp`.
+     * @param {object} params
+     * @param {string} params.sourcePath - Local source path.
+     * @param {string} params.podName - Target pod name.
+     * @param {string} params.namespace - Pod namespace.
+     * @param {string} params.destPath - Destination path inside the container.
+     * @returns {boolean} `true` on success, `false` on error.
+     * @memberof UnderpostKubectl
+     */
+    cpTo({ sourcePath, podName, namespace, destPath }) {
+      try {
+        const command = `sudo kubectl cp ${sourcePath} ${namespace}/${podName}:${destPath}`;
+        Underpost.kubectl.run(command, { context: `copy to pod ${podName}` });
+        return true;
+      } catch (error) {
+        logger.error('Failed to copy file to pod', { sourcePath, podName, destPath, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Copies a file from a pod to the local filesystem via `kubectl cp`.
+     * @param {object} params
+     * @param {string} params.podName - Source pod name.
+     * @param {string} params.namespace - Pod namespace.
+     * @param {string} params.sourcePath - Source path inside the container.
+     * @param {string} params.destPath - Local destination path.
+     * @returns {boolean} `true` on success, `false` on error.
+     * @memberof UnderpostKubectl
+     */
+    cpFrom({ podName, namespace, sourcePath, destPath }) {
+      try {
+        const command = `sudo kubectl cp ${namespace}/${podName}:${sourcePath} ${destPath}`;
+        Underpost.kubectl.run(command, { context: `copy from pod ${podName}` });
+        return true;
+      } catch (error) {
+        logger.error('Failed to copy file from pod', { podName, sourcePath, destPath, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Checks whether a file exists inside a pod container.
+     * @param {object} params
+     * @param {string} params.podName - Pod name.
+     * @param {string} params.path - Absolute path inside the container to test.
+     * @returns {boolean} `true` if the file exists.
+     * @memberof UnderpostKubectl
+     */
+    existsFile({ podName, path }) {
+      const result = shellExec(`kubectl exec ${podName} -- test -f ${path} && echo "true" || echo "false"`, {
+        stdout: true,
+        disableLog: true,
+        silent: true,
+      }).trim();
+      return result === 'true';
+    },
+
+    /**
+     * Returns a filtered list of pods from the cluster.
+     * Supports wildcard glob patterns on pod names and optional deployId substring filtering.
+     * @param {object} [criteria={}] - Filter criteria.
+     * @param {string} [criteria.deployId] - Substring to match against pod names (forwards to `get`).
+     * @param {string} [criteria.podNames] - Comma-separated glob patterns (supports `*`).
+     * @param {string} [criteria.namespace='default'] - Kubernetes namespace to query.
+     * @returns {Array<object>} Filtered pod rows from `get`.
+     * @memberof UnderpostKubectl
+     */
+    getFilteredPods(criteria = {}) {
+      const { podNames, namespace = 'default', deployId } = criteria;
+      try {
+        let pods = Underpost.kubectl.get(deployId || '', 'pods', namespace);
+        if (podNames) {
+          const patterns = podNames.split(',').map((p) => p.trim());
+          pods = pods.filter((pod) =>
+            patterns.some((pattern) => new RegExp('^' + pattern.replace(/\*/g, '.*') + '$').test(pod.NAME)),
+          );
+        }
+        logger.info(`Found ${pods.length} pod(s) matching criteria`, { criteria, podNames: pods.map((p) => p.NAME) });
+        return pods;
+      } catch (error) {
+        logger.error('Error filtering pods', { error: error.message, criteria });
+        return [];
+      }
+    },
+  };
+}
+
+export default UnderpostKubectl;