@underpostnet/cyberia 3.2.80

package/src/cli/ipfs.js

@@ -0,0 +1,182 @@
+/**
+ * IPFS Cluster module for managing ipfs-cluster StatefulSet deployment on Kubernetes.
+ * @module src/cli/ipfs.js
+ * @namespace UnderpostIPFS
+ */
+
+import { loggerFactory } from '../server/logger.js';
+import { shellExec } from '../server/process.js';
+import fs from 'fs-extra';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @class UnderpostIPFS
+ * @description Manages deployment of an ipfs-cluster StatefulSet on Kubernetes.
+ * Credentials (cluster secret + peer identity) are generated once and persisted
+ * to engine-private/ so the cluster identity survives redeployments.
+ * @memberof UnderpostIPFS
+ */
+class UnderpostIPFS {
+  static API = {
+    /**
+     * @method resolveCredentials
+     * @description Resolves the IPFS cluster credentials from engine-private/ if they
+     * already exist, otherwise generates new ones (hex cluster secret + peer identity
+     * via ipfs-cluster-service init) and persists them with mode 0o600.
+     * @param {string} privateDir - Absolute path to the engine-private directory.
+     * @returns {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string } }}
+     * @memberof UnderpostIPFS
+     */
+    resolveCredentials(privateDir) {
+      const secretPath = `${privateDir}/ipfs-cluster-secret`;
+      const identityPath = `${privateDir}/ipfs-cluster-identity.json`;
+
+      if (fs.existsSync(secretPath) && fs.existsSync(identityPath)) {
+        logger.info('Reusing existing IPFS cluster credentials from engine-private/');
+        return {
+          CLUSTER_SECRET: fs.readFileSync(secretPath, 'utf8').trim(),
+          IDENTITY_JSON: JSON.parse(fs.readFileSync(identityPath, 'utf8')),
+        };
+      }
+
+      logger.info('Generating new IPFS cluster credentials and persisting to engine-private/');
+
+      // ipfs-cluster-service requires CLUSTER_SECRET as a 64-char hex string.
+      // base64 (openssl rand -base64 32) contains '/', '+', '=' which are invalid hex bytes.
+      const CLUSTER_SECRET = shellExec("od -vN 32 -An -tx1 /dev/urandom | tr -d ' \\n'", {
+        stdout: true,
+      }).trim();
+
+      const tmpDir = '/tmp/ipfs-cluster-identity';
+      shellExec(`rm -rf ${tmpDir} && mkdir -p ${tmpDir}`);
+      shellExec(`docker run --rm -v ${tmpDir}:/data/ipfs-cluster ipfs/ipfs-cluster init -f`);
+      const IDENTITY_JSON = JSON.parse(shellExec(`cat ${tmpDir}/identity.json`, { stdout: true }).trim());
+      shellExec(`rm -rf ${tmpDir}`);
+
+      fs.ensureDirSync(privateDir);
+      fs.writeFileSync(secretPath, CLUSTER_SECRET, { mode: 0o600 });
+      fs.writeFileSync(identityPath, JSON.stringify(IDENTITY_JSON, null, 2), { mode: 0o600 });
+
+      logger.info(`IPFS cluster credentials saved (peer ID: ${IDENTITY_JSON.id})`);
+
+      return { CLUSTER_SECRET, IDENTITY_JSON };
+    },
+
+    /**
+     * @method teardown
+     * @description Deletes the existing ipfs-cluster StatefulSet, its Kubernetes Secret,
+     * env ConfigMap, and all PVCs so the next deployment initialises a clean data volume
+     * (ensuring the correct datastore profile is applied by the init container).
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {number} ipfsReplicas - Number of replicas whose PVCs must be removed.
+     * @memberof UnderpostIPFS
+     */
+    teardown(options, ipfsReplicas) {
+      logger.info(`Tearing down existing ipfs-cluster deployment in namespace '${options.namespace}'`);
+      shellExec(`kubectl delete statefulset ipfs-cluster -n ${options.namespace} --ignore-not-found`);
+      shellExec(`kubectl delete secret ipfs-cluster-secret -n ${options.namespace} --ignore-not-found`);
+      shellExec(`kubectl delete configmap env-config -n ${options.namespace} --ignore-not-found`);
+      for (let i = 0; i < ipfsReplicas; i++) {
+        shellExec(
+          `kubectl delete pvc cluster-storage-ipfs-cluster-${i} ipfs-storage-ipfs-cluster-${i} -n ${options.namespace} --ignore-not-found`,
+        );
+      }
+    },
+
+    /**
+     * @method applySecrets
+     * @description Creates (or idempotently updates) the Kubernetes Secret and env ConfigMap
+     * that the StatefulSet pods read at startup.
+     * - Secret `ipfs-cluster-secret`: cluster-secret + bootstrap-peer-priv-key
+     * - ConfigMap `env-config`: bootstrap-peer-id + CLUSTER_SVC_NAME
+     * @param {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string } }} credentials
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @memberof UnderpostIPFS
+     */
+    applySecrets({ CLUSTER_SECRET, IDENTITY_JSON }, options) {
+      logger.info('Applying IPFS cluster Kubernetes Secret and env ConfigMap');
+
+      shellExec(
+        `kubectl create secret generic ipfs-cluster-secret \
+--from-literal=cluster-secret=${CLUSTER_SECRET} \
+--from-literal=bootstrap-peer-priv-key=${IDENTITY_JSON.private_key} \
+--dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
+      );
+
+      shellExec(
+        `kubectl create configmap env-config \
+--from-literal=bootstrap-peer-id=${IDENTITY_JSON.id} \
+--from-literal=CLUSTER_SVC_NAME=ipfs-cluster \
+--dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
+      );
+    },
+
+    /**
+     * @method applyManifests
+     * @description Applies host-level sysctl tuning (Kind clusters only), the storage class,
+     * the kustomize manifests, and scales the StatefulSet to the requested replica count.
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {boolean} [options.kubeadm] - Whether the cluster is Kubeadm-based.
+     * @param {boolean} [options.k3s] - Whether the cluster is K3s-based.
+     * @param {string} underpostRoot - Absolute path to the underpost project root.
+     * @param {number} ipfsReplicas - Desired replica count.
+     * @memberof UnderpostIPFS
+     */
+    applyManifests(options, underpostRoot, ipfsReplicas) {
+      // Apply UDP buffer sysctl on every Kind node so QUIC (used by IPFS) can reach the
+      // recommended 7.5 MB buffer size. Kind nodes are containers and do NOT inherit the
+      // host sysctl values, so this must be set via docker exec on each node directly.
+      shellExec(
+        `sudo sysctl -w net.core.rmem_max=7500000
+sudo sysctl -w net.core.wmem_max=7500000`,
+      );
+
+      shellExec(`kubectl apply -f ${underpostRoot}/manifests/ipfs/storage-class.yaml`);
+      shellExec(`kubectl apply -k ${underpostRoot}/manifests/ipfs -n ${options.namespace}`);
+
+      // statefulset.yaml hardcodes replicas: 3 as the ceiling; scale down here if needed.
+      shellExec(`kubectl scale statefulset ipfs-cluster --replicas=${ipfsReplicas} -n ${options.namespace}`);
+    },
+
+    /**
+     * @method deploy
+     * @description Full orchestration of the ipfs-cluster StatefulSet deployment:
+     * optionally pulls images, resolves or generates credentials, tears down any existing
+     * deployment, applies secrets, applies manifests, and waits for all pods to be Running.
+     * @param {object} options - Cluster init options forwarded from UnderpostCluster.API.init.
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @param {boolean} [options.pullImage] - Whether to pull container images first.
+     * @param {boolean} [options.kubeadm] - Whether the cluster is Kubeadm-based.
+     * @param {boolean} [options.k3s] - Whether the cluster is K3s-based.
+     * @param {string|number} [options.replicas] - Override replica count (defaults to 3).
+     * @param {string} underpostRoot - Absolute path to the underpost project root.
+     * @memberof UnderpostIPFS
+     */
+    async deploy(options, underpostRoot) {
+      if (options.pullImage === true) {
+        Underpost.cluster.pullImage('ipfs/kubo:latest', options);
+        Underpost.cluster.pullImage('ipfs/ipfs-cluster:latest', options);
+      }
+
+      const credentials = Underpost.ipfs.resolveCredentials(`${underpostRoot}/engine-private`);
+
+      const ipfsReplicas = options.replicas ? parseInt(options.replicas) : 3;
+
+      Underpost.ipfs.teardown(options, ipfsReplicas);
+      Underpost.ipfs.applySecrets(credentials, options);
+      Underpost.ipfs.applyManifests(options, underpostRoot, ipfsReplicas);
+
+      logger.info(`Waiting for ${ipfsReplicas} ipfs-cluster pod(s) to reach Running state`);
+      for (let i = 0; i < ipfsReplicas; i++) {
+        await Underpost.test.statusMonitor(`ipfs-cluster-${i}`, 'Running', 'pods', 1000, 60 * 15);
+      }
+    },
+  };
+}
+
+export default UnderpostIPFS;

package/src/cli/kickstart.js

@@ -0,0 +1,271 @@
+/**
+ * Kickstart configuration generator for Underpost Engine
+ * @module src/cli/kickstart.js
+ * @namespace UnderpostKickStart
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { loggerFactory } from '../server/logger.js';
+
+const logger = loggerFactory(import.meta);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class UnderpostKickStart {
+  static API = {
+    /**
+     * @method kickstartHeader
+     * @description Generates the kickstart header section with template variables.
+     * @param {object} options
+     * @param {string} [options.lang='en_US.UTF-8']
+     * @param {string} [options.keyboard='us']
+     * @param {string} [options.timezone='America/New_York']
+     * @param {string} [options.rootPassword]
+     * @memberof UnderpostKickStart
+     * @returns {string}
+     */
+    kickstartHeader: ({ lang = 'en_US.UTF-8', keyboard = 'us', timezone = 'America/New_York', rootPassword = '' }) => {
+      return [
+        '# Rocky Linux 9 Kickstart - Ephemeral Anaconda Live Environment with SSHD',
+        'cmdline',
+        'eula --agreed',
+        `keyboard --vckeymap=${keyboard} --xlayouts='${keyboard}'`,
+        `lang ${lang}`,
+        'network --bootproto=dhcp --device=link --activate --onboot=yes',
+        `timezone ${timezone} --utc`,
+        rootPassword ? `rootpw --plaintext ${rootPassword}` : 'rootpw --lock',
+        'firstboot --disable',
+        'skipx',
+      ].join('\n');
+    },
+
+    /**
+     * @method kickstartPreVariables
+     * @description Generates the shell variable-assignment block injected at the top of the
+     * kickstart `%pre` script. These variables drive both the ephemeral commissioning runtime
+     * and the unattended disk installer in `scripts/rocky-kickstart.sh`. Passwords are emitted
+     * base64-encoded (`*_B64`) and decoded by an in-script `ks_b64d` helper; all other values
+     * are single-quote escaped so arbitrary content survives the shell/heredoc layers.
+     * @param {object} options - Variable values to bake into the `%pre` block.
+     * @param {string} [options.rootPassword=''] - root console password (base64-encoded).
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user (defaults to MAAS_ADMIN_USERNAME).
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.timezone=''] - IANA timezone configured in the deployed OS (e.g. America/Santiago).
+     * @param {string} [options.keyboardLayout=''] - Console/X11 keyboard layout for the deployed OS (e.g. es).
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server for this host (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk (e.g. /dev/nvme0n1); empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the ephemeral runtime self-installs after a fallback timeout if no remote trigger arrives.
+     * @memberof UnderpostKickStart
+     * @returns {string} Newline-joined bash variable assignments.
+     */
+    kickstartPreVariables: ({
+      rootPassword = '',
+      authorizedKeys = '',
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
+      timezone = '',
+      keyboardLayout = '',
+      chronyConfPath = '/etc/chrony.conf',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
+    }) => {
+      const sanitizedKeys = (authorizedKeys || '').trim();
+      // Passwords are passed base64-encoded so arbitrary characters (quotes,
+      // spaces, $, etc.) survive every shell/heredoc layer intact. base64 output
+      // never contains single quotes. Decoding tries `base64` then falls back to
+      // python3 so a minimal Anaconda environment can never yield empty passwords.
+      const b64 = (v) => Buffer.from(String(v || ''), 'utf8').toString('base64');
+      const sq = (v) => `'${String(v || '').replace(/'/g, "'\\''")}'`;
+      return [
+        `ks_b64d() { printf %s "$1" | base64 -d 2>/dev/null || printf %s "$1" | python3 -c 'import sys,base64;sys.stdout.buffer.write(base64.b64decode(sys.stdin.read().strip()))' 2>/dev/null; }`,
+        `ROOT_PASS_B64='${b64(rootPassword)}'`,
+        `ADMIN_PASS_B64='${b64(adminPassword || rootPassword)}'`,
+        `DEPLOY_PASS_B64='${b64(deployPassword)}'`,
+        `ROOT_PASS="$(ks_b64d "$ROOT_PASS_B64")"`,
+        `ADMIN_PASS="$(ks_b64d "$ADMIN_PASS_B64")"`,
+        `DEPLOY_PASS="$(ks_b64d "$DEPLOY_PASS_B64")"`,
+        `AUTHORIZED_KEYS=${sq(sanitizedKeys)}`,
+        `ADMIN_USER=${sq(adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas')}`,
+        `DEPLOY_USER=${sq(deployUsername)}`,
+        `NET_IP=${sq(netIp)}`,
+        `NET_PREFIX='${parseInt(netPrefix, 10) || 24}'`,
+        `NET_GATEWAY=${sq(netGateway)}`,
+        `NET_DNS=${sq(netDns)}`,
+        `TIMEZONE=${sq(timezone)}`,
+        `KEYBOARD_LAYOUT=${sq(keyboardLayout)}`,
+        `CHRONY_CONF_PATH=${sq(chronyConfPath || '/etc/chrony.conf')}`,
+        `BOOTSTRAP_URL=${sq(bootstrapUrl)}`,
+        `WORKFLOW_ID=${sq(workflowId)}`,
+        `SYSTEM_ID=${sq(systemId)}`,
+        `TARGET_HOSTNAME=${sq(targetHostname)}`,
+        `SSH_PORT='${sshPort || 22}'`,
+        `INSTALL_DISK_HINT=${sq(installDiskHint)}`,
+        `AUTO_INSTALL='${autoInstall ? '1' : '0'}'`,
+      ].join('\n');
+    },
+
+    /**
+     * @method kickstartFactory
+     * @description Generates a complete kickstart configuration by combining the header,
+     * the `%pre` variable-assignment block, and the `scripts/rocky-kickstart.sh` body.
+     * @param {object} options - Kickstart generation options.
+     * @param {string} [options.lang='en_US.UTF-8'] - System language for the ephemeral runtime.
+     * @param {string} [options.keyboard='us'] - Keyboard layout for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.timezone='America/New_York'] - Timezone for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.rootPassword=process.env.MAAS_ADMIN_PASS] - root console password.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user created in the deployed OS.
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk; empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the runtime self-installs after a fallback timeout.
+     * @memberof UnderpostKickStart
+     * @returns {string} The full kickstart (ks.cfg) source.
+     */
+    kickstartFactory: ({
+      lang = 'en_US.UTF-8',
+      keyboard = 'us',
+      timezone = 'America/New_York',
+      chronyConfPath = '/etc/chrony.conf',
+      rootPassword = process.env.MAAS_ADMIN_PASS,
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
+      authorizedKeys = '',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
+    }) => {
+      const resolvedAdminUsername = adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas';
+      const header = UnderpostKickStart.API.kickstartHeader({ lang, keyboard, timezone, rootPassword });
+      const variables = UnderpostKickStart.API.kickstartPreVariables({
+        rootPassword,
+        authorizedKeys,
+        adminUsername: resolvedAdminUsername,
+        adminPassword,
+        deployUsername,
+        deployPassword,
+        netIp,
+        netPrefix,
+        netGateway,
+        netDns,
+        timezone,
+        keyboardLayout: keyboard,
+        chronyConfPath,
+        bootstrapUrl,
+        workflowId,
+        systemId,
+        targetHostname,
+        sshPort,
+        installDiskHint,
+        autoInstall,
+      });
+
+      const scriptPath = path.resolve(__dirname, '../../scripts/rocky-kickstart.sh');
+      const scriptBody = fs.readFileSync(scriptPath, 'utf8');
+
+      return [
+        header,
+        '',
+        '%pre --interpreter=/bin/bash --log=/tmp/ks-pre.log --erroronfail',
+        '#!/bin/bash',
+        variables,
+        '',
+        scriptBody,
+        '%end',
+      ].join('\n');
+    },
+
+    /**
+     * @method kernelParamsFactory
+     * @description Appends kickstart-specific kernel parameters (inst.ks, inst.repo, inst.text, inst.sshd).
+     * @param {string} macAddress - The MAC address of the target machine.
+     * @param {array} cmd - The existing array of kernel parameters.
+     * @param {object} options - Options for generating kernel parameters.
+     * @param {string} options.ipDhcpServer - The IP address of the DHCP server.
+     * @param {number} [options.bootstrapHttpServerPort=8888] - Port for the bootstrap HTTP server.
+     * @param {string} options.hostname - The hostname of the target machine.
+     * @param {string} [options.architecture='amd64'] - The target architecture.
+     * @memberof UnderpostKickStart
+     * @returns {array}
+     */
+    kernelParamsFactory(
+      macAddress,
+      cmd = [],
+      options = { ipDhcpServer: '', bootstrapHttpServerPort: 8888, hostname: '', architecture: 'amd64' },
+    ) {
+      const { ipDhcpServer, bootstrapHttpServerPort, hostname, architecture } = options;
+      const repoArch = architecture && architecture.match('arm64') ? 'aarch64' : 'x86_64';
+      return cmd.concat([
+        `inst.ks=http://${ipDhcpServer}:${bootstrapHttpServerPort}/${hostname}/ks.cfg`,
+        `inst.repo=http://dl.rockylinux.org/pub/rocky/9/BaseOS/${repoArch}/os/`,
+        `inst.text`,
+        `inst.sshd`,
+      ]);
+    },
+
+    /**
+     * @method httpServerStaticFactory
+     * @description Writes kickstart ks.cfg file to the bootstrap HTTP server path.
+     * @param {object} params
+     * @param {string} params.bootstrapHttpServerPath
+     * @param {string} params.hostname
+     * @param {string} params.kickstartSrc
+     * @memberof UnderpostKickStart
+     * @returns {void}
+     */
+    httpServerStaticFactory({ bootstrapHttpServerPath, hostname, kickstartSrc }) {
+      if (!kickstartSrc) return;
+      const dest = `${bootstrapHttpServerPath}/${hostname}/ks.cfg`;
+      fs.writeFileSync(dest, kickstartSrc, 'utf8');
+      logger.info(`Kickstart file written to ${dest}`);
+    },
+  };
+}
+
+export default UnderpostKickStart;

package/src/cli/kubectl.js

@@ -0,0 +1,214 @@
+/**
+ * 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 = '') {
+      // Existence-check style: a missing kubectl context, a non-existent
+      // namespace, or no pods matching the filter must return an empty
+      // list (not throw). silentOnError keeps the legacy contract.
+      const raw = shellExec(
+        `sudo kubectl get ${kindType}${namespace ? ` -n ${namespace}` : ` --all-namespaces`} -o wide`,
+        { stdout: true, disableLog: true, silent: true, silentOnError: 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;