cyberia 3.1.3 → 3.2.9

package/src/cli/fs.js

@@ -75,6 +75,7 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @param {string} [options.storageFilePath=''] - The path to the storage configuration file.
      * @returns {Promise<void>} A promise that resolves when the recursive callback is complete.
      * @memberof UnderpostFileStorage
@@ -88,10 +89,50 @@ class UnderpostFileStorage {
         force: false,
         pull: false,
         git: false,
+        omitUnzip: false,
         storageFilePath: '',
       },
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
+
+      // In recursive remove mode, delete every tracked storage key under the requested path,
+      // even when local files/directories are already missing.
+      if (options.rm === true) {
+        const normalizedPath = typeof path === 'string' ? path.trim() : '';
+        const basePath = normalizedPath.replace(/\/+$/, '');
+        const hasPathFilter = basePath.length > 0;
+
+        const associatedPaths = Object.keys(storage || {}).filter((storedPath) => {
+          if (!hasPathFilter) return true;
+          return storedPath === basePath || storedPath.startsWith(`${basePath}/`);
+        });
+
+        for (const associatedPath of associatedPaths) {
+          await Underpost.fs.delete(associatedPath);
+          if (storage) delete storage[associatedPath];
+        }
+
+        if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
+
+        Underpost.fs.writeStorageConf(storage, storageConf);
+
+        if (associatedPaths.length === 0)
+          logger.warn('No associated tracked storage paths found', { path: hasPathFilter ? basePath : '*' });
+        else
+          logger.info('Removed associated tracked storage paths', {
+            path: hasPathFilter ? basePath : '*',
+            removed: associatedPaths.length,
+          });
+
+        if (options.git === true) {
+          const gitPath = hasPathFilter ? basePath : '.';
+          shellExec(`cd ${gitPath} && git add .`);
+          shellExec(`underpost cmt ${gitPath} feat`);
+        }
+
+        return;
+      }
+
       const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
       for (const relativePath of deleteFiles) {
         const _path = path + '/' + relativePath;
@@ -101,13 +142,20 @@ class UnderpostFileStorage {
         }
       }
       if (options.pull === true) {
+        let pullSkipCount = 0;
         for (const _path of Object.keys(storage)) {
           if (!fs.existsSync(_path) || options.force === true) {
             if (options.force === true && fs.existsSync(_path)) fs.removeSync(_path);
             await Underpost.fs.pull(_path, options);
-          } else logger.warn(`Pull path already exists`, _path);
+          } else pullSkipCount++;
+        }
+        if (pullSkipCount > 0) logger.warn(`Pull skipped ${pullSkipCount} files that already exist`);
+        // Only run git init/commit when the caller explicitly requests git tracking (--git flag).
+        // For bundle pulls into ./build the git step is unwanted and would error on a non-repo path.
+        if (options.git === true) {
+          Underpost.repo.initLocalRepo({ path });
+          shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`);
         }
-        shellExec(`cd ${path} && git init && git add . && git commit -m "Base pull state"`);
       } else {
         const files =
           options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
@@ -140,12 +188,13 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @returns {Promise<void>} A promise that resolves when the callback is complete.
      * @memberof UnderpostFileStorage
      */
     async callback(
       path,
-      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false },
+      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
       if (options.recursive === true || options.git === true)
         return await Underpost.fs.recursiveCallback(path, options);
@@ -158,11 +207,13 @@ class UnderpostFileStorage {
      * @description Uploads a file to Cloudinary.
      * @param {string} path - The path to the file to upload.
      * @param {object} [options] - An object containing options for the upload.
-     * @param {boolean} [options.force=false] - Flag to force file operations.
+     * @param {string} [options.deployId=''] - The identifier for the deployment (used to locate the storage config file).
+     * @param {boolean} [options.force=false] - Flag to force file operations (overwrites existing remote asset).
      * @param {string} [options.storageFilePath=''] - The path to the storage configuration file.
      * @returns {Promise<object>} A promise that resolves to the upload result.
      * @memberof UnderpostFileStorage
      */
+
     async upload(
       path,
       options = { rm: false, recursive: false, deployId: '', force: false, pull: false, storageFilePath: '' },
@@ -188,22 +239,45 @@ class UnderpostFileStorage {
      * @method pull
      * @description Pulls a file from Cloudinary.
      * @param {string} path - The path to the file to pull.
+     * @param {object} [options] - Pull options.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
+     * @param {boolean} [options.force=false] - If true, re-download even if the local zip already exists.
      * @returns {Promise<void>} A promise that resolves when the file is pulled.
      * @memberof UnderpostFileStorage
      */
-    async pull(path) {
+    async pull(path, options = { omitUnzip: false, force: false }) {
       Underpost.fs.cloudinaryConfig();
       const folder = dir.dirname(path);
       if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+      const zipPath = `${path}.zip`;
+
+      if (options.omitUnzip === true && options.force !== true && fs.existsSync(zipPath)) {
+        logger.warn('pull skipped, zip already exists and omit-unzip is enabled', { path, zipPath });
+        return;
+      }
+
       const downloadResult = await cloudinary.utils.download_archive_url({
         public_ids: [path],
         resource_type: 'raw',
       });
       logger.info('download result', downloadResult);
-      await Downloader.downloadFile(downloadResult, path + '.zip');
-      path = Underpost.fs.zip2File(path + '.zip');
-      fs.removeSync(path + '.zip');
+      await Downloader.downloadFile(downloadResult, zipPath);
+
+      if (options.omitUnzip === true) {
+        logger.warn('omit unzip enabled, keeping downloaded zip file', { path, zipPath });
+        return;
+      }
+
+      path = Underpost.fs.zip2File(zipPath);
+      fs.removeSync(`${path}.zip`);
     },
+    /**
+     * @method delete
+     * @description Deletes a file from Cloudinary by its public ID.
+     * @param {string} path - The path (public ID) of the file to delete.
+     * @returns {Promise<object>} A promise that resolves to the Cloudinary delete result.
+     * @memberof UnderpostFileStorage
+     */
     async delete(path) {
       Underpost.fs.cloudinaryConfig();
       const deleteResult = await cloudinary.api

package/src/cli/image.js

@@ -99,6 +99,7 @@ class UnderpostImage {
       if (!path) path = '.';
       if (!imageName) imageName = `rockylinux9-underpost:${Underpost.version}`;
       if (!imagePath) imagePath = '.';
+      if (imageName.match('/')) imageName = imageName.split('/')[1];
       if (!version) version = 'latest';
       version = imageName && imageName.match(':') ? '' : `:${version}`;
       const podManImg = `localhost/${imageName}${version}`;
@@ -178,6 +179,12 @@ class UnderpostImage {
      * @memberof UnderpostImage
      */
     pullDockerHubImage(options = { k3s: false, kubeadm: false, kind: false, dockerhubImage: '', version: '' }) {
+      if (options.dockerhubImage && options.dockerhubImage.startsWith('localhost')) {
+        logger.warn(`[image] pullDockerHubImage skipped — local image cannot be pulled from Docker Hub`, {
+          dockerhubImage: options.dockerhubImage,
+        });
+        return;
+      }
       if (options.dockerhubImage === 'underpost') {
         options.dockerhubImage = 'underpost/underpost-engine';
         if (!options.version) options.version = Underpost.version;
@@ -185,7 +192,42 @@ class UnderpostImage {
       if (!options.version) options.version = 'latest';
       const version = options.dockerhubImage && options.dockerhubImage.match(':') ? '' : `:${options.version}`;
       const image = `${options.dockerhubImage}${version}`;
-      if (options.kind === true) {
+      const targetKind = options.kind === true;
+      const targetK3s = options.k3s === true;
+      const targetKubeadm = options.kubeadm === true || (!targetKind && !targetK3s);
+
+      const requestedRepo = image.replace(/:[^/]+$/, '');
+      const requestedTag = image.match(/:([^/]+)$/)?.[1] || 'latest';
+      const normalizeRepo = (repo = '') =>
+        repo
+          .trim()
+          .replace(/^localhost\//, '')
+          .replace(/^docker\.io\//, '')
+          .replace(/^library\//, '');
+
+      const currentImages = UnderpostImage.API.list({
+        kind: targetKind,
+        kubeadm: targetKubeadm,
+        k3s: targetK3s,
+        log: false,
+      });
+
+      const existsInCluster = currentImages.some((row) => {
+        const rowImageRaw = String(row.IMAGE || row.image || '').trim();
+        if (!rowImageRaw) return false;
+        const rowImage = rowImageRaw.replace(/:[^/]+$/, '');
+        const rowTag = String(row.TAG || rowImageRaw.match(/:([^/]+)$/)?.[1] || '').trim();
+        return normalizeRepo(rowImage) === normalizeRepo(requestedRepo) && rowTag === requestedTag;
+      });
+
+      if (existsInCluster) {
+        logger.info(`[image] pull skipped. Image already loaded`, {
+          image,
+          clusterType: targetKind ? 'kind' : targetK3s ? 'k3s' : 'kubeadm',
+        });
+        return;
+      }
+      if (targetKind) {
         shellExec(`docker pull ${image}`);
         shellExec(`sudo kind load docker-image ${image}`);
       } else {

package/src/cli/index.js

@@ -46,6 +46,9 @@ program
   .option('--sync-env-port', 'Sync environment port assignments across all deploy IDs')
   .option('--single-replica', 'Build single replica folders instead of full client')
   .option('--build-zip', 'Create zip files of the builds')
+  .option('--split <mb>', 'Split generated zip files into parts of the specified size in MB')
+  .option('--unzip <build-prefix>', 'Extract a built client zip or split zip parts using the given build prefix')
+  .option('--merge-zip <build-prefix>', 'Merge split ZIP parts back into a single ZIP file for the given build prefix')
   .option('--lite-build', 'Skip full build (default is full build)')
   .option('--icons-build', 'Build icons')
   .description('Builds client assets, single replicas, and/or syncs environment ports.')
@@ -62,6 +65,11 @@ program
   .option('--build', 'Triggers the client-side application build process.')
   .option('--underpost-quickly-install', 'Uses Underpost Quickly Install for dependency installation.')
   .option('--skip-pull-base', 'Skips cloning repositories, uses current workspace code directly.')
+  .option('--skip-full-build', 'Skips the full client bundle build during deployment.')
+  .option(
+    '--pull-bundle',
+    'Downloads the pre-built client bundle from Cloudinary via pull-bundle before starting. Use together with --skip-full-build to skip the local build entirely.',
+  )
   .action(Underpost.start.callback)
   .description('Initiates application servers, build pipelines, or other defined services based on the deployment ID.');
 
@@ -87,7 +95,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 +116,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);
 
@@ -219,6 +234,7 @@ program
   .option('--ban-egress-clear', 'Clears all banned egress IP addresses.')
   .option('--ban-both-add', 'Adds IP addresses to both banned ingress and egress lists.')
   .option('--ban-both-remove', 'Removes IP addresses from both banned ingress and egress lists.')
+  .option('--mac', 'Prints the MAC address of the main network interface.')
   .description('Displays the current public machine IP addresses.')
   .action(Underpost.dns.ipDispatcher);
 
@@ -308,6 +324,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.')
@@ -319,6 +338,14 @@ program
     'Sets the local:remote port to expose when --expose is active (overrides auto-detected service port).',
   )
   .option('--cmd <cmd>', 'Custom initialization command for deployment (comma-separated commands).')
+  .option(
+    '--skip-full-build',
+    'Skip client bundle rebuild; container will pull pre-built bundle via pull-bundle instead.',
+  )
+  .option(
+    '--pull-bundle',
+    'Explicitly pull the pre-built client bundle from Cloudinary inside the container. Use together with --skip-full-build.',
+  )
   .description('Manages application deployments, defaulting to deploying development pods.')
   .action(Underpost.deploy.callback);
 
@@ -327,10 +354,14 @@ program
   .argument('<platform>', `The secret management platform. Options: ${Object.keys(Underpost.secret).join(', ')}.`)
   .option('--init', 'Initializes the secrets platform environment.')
   .option('--create-from-file <path-env-file>', 'Creates secrets from a specified environment file.')
+  .option('--create-from-env', 'Creates secrets from container environment variables (envFrom: secretRef).')
+  .option('--global-clean', 'Removes all filesystem traces of secrets (engine-private, .env, conf cache).')
   .option('--list', 'Lists all available secrets for the platform.')
   .description(`Manages secrets for various platforms.`)
   .action((...args) => {
+    if (args[1].globalClean) return Underpost.secret.globalSecretClean();
     if (args[1].createFromFile) return Underpost.secret[args[0]].createFromEnvFile(args[1].createFromFile);
+    if (args[1].createFromEnv) return Underpost.secret[args[0]].createFromContainerEnv();
     if (args[1].list) return Underpost.secret[args[0]].list();
     if (args[1].init) return Underpost.secret[args[0]].init();
   });
@@ -413,6 +444,7 @@ program
   .option('--kubeadm', 'Enables the kubeadm context for database operations.')
   .option('--kind', 'Enables the kind context for database operations.')
   .option('--k3s', 'Enables the k3s context for database operations.')
+  .option('--repo-backup', 'Backs up repositories (git commit+push) inside deployment pods via kubectl exec.')
   .description(
     'Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration.',
   )
@@ -429,6 +461,7 @@ program
   .option('--instances', 'Apply to instance data collection')
   .option('--generate', 'Generate cluster metadata')
   .option('--itc', 'Apply under container execution context')
+  .option('--dev', 'Sets the development cli context')
   .description('Manages cluster metadata operations, including import and export.')
   .action(Underpost.db.clusterMetadataBackupCallback);
 
@@ -458,7 +491,6 @@ program
     '--create-job-now',
     'After applying manifests, immediately create a Job from each CronJob (requires --apply).',
   )
-  .option('--ssh', 'Execute backup commands via SSH on the remote node instead of locally.')
   .description('Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests.')
   .action(Underpost.cron.callback);
 
@@ -470,6 +502,7 @@ program
   .option('--recursive', 'Uploads files recursively from the specified path.')
   .option('--deploy-id <deploy-id>', 'Specifies the deployment configuration ID for file operations.')
   .option('--pull', 'Downloads the specified file.')
+  .option('--omit-unzip', 'With --pull, keeps the downloaded .zip file and skips extraction.')
   .option('--force', 'Forces the action, overriding any warnings or conflicts.')
   .option('--storage-file-path <storage-file-path>', 'Specifies a custom file storage path.')
   .description('Manages file storage, defaulting to file upload operations.')
@@ -597,7 +630,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('--log-type <log-type>', 'Sets the log type for the runner execution.')
+  .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
   .option('--deploy-id <deploy-id>', 'Sets deploy id context for the runner execution.')
   .option('--user <user>', 'Sets user context for the runner execution.')
   .option('--hosts <hosts>', 'Comma-separated list of hosts for the runner execution.')
@@ -640,6 +673,15 @@ 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).')
+  .option(
+    '--skip-full-build',
+    'Skip client bundle rebuild; triggers pull-bundle in container startup (supported by: sync, template-deploy).',
+  )
+  .option(
+    '--pull-bundle',
+    'Explicitly download the pre-built client bundle from Cloudinary inside the container (supported by: sync, template-deploy). Use together with --skip-full-build.',
+  )
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
@@ -764,4 +806,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;