cyberia 3.2.22 → 3.2.70

package/src/cli/fs.js

@@ -64,6 +64,31 @@ class UnderpostFileStorage {
     writeStorageConf(storage, storageConf) {
       if (storage) fs.writeFileSync(storageConf, JSON.stringify(storage, null, 4), 'utf8');
     },
+    /**
+     * @method gitTrack
+     * @description Optional, non-fatal Git tracking layer. Any Git error is logged and swallowed
+     * so it can never interrupt or roll back the canonical `storage.*.json` workflow.
+     * @param {string} gitPath - The working directory to stage/commit.
+     * @param {object} [options] - Tracking options.
+     * @param {boolean} [options.init=false] - If true, initialize a local repo before staging.
+     * @param {string} [options.message=''] - Explicit commit message; when omitted, `underpost cmt` is used.
+     * @memberof UnderpostFileStorage
+     */
+    gitTrack(gitPath, options = { init: false, message: '' }) {
+      try {
+        if (options.init === true) Underpost.repo.initLocalRepo({ path: gitPath });
+        shellExec(`cd ${gitPath} && git add .`, { silentOnError: true, silent: true, disableLog: true });
+        if (options.message)
+          shellExec(`cd ${gitPath} && git commit -m "${options.message}"`, {
+            silentOnError: true,
+            silent: true,
+            disableLog: true,
+          });
+        else shellExec(`underpost cmt ${gitPath} feat`, { silentOnError: true, silent: true, disableLog: true });
+      } catch (error) {
+        logger.warn('git tracking skipped (non-fatal)', { gitPath, error: error?.message });
+      }
+    },
     /**
      * @method recursiveCallback
      * @description Recursively processes files and directories based on the provided options.
@@ -95,6 +120,17 @@ class UnderpostFileStorage {
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
 
+      // ── Single-file handling: when path is a file (not a directory), use parent dir
+      //    as the git working directory and process just that one file. ──────────────
+      let isSingleFile = false;
+      let parentDir = path;
+      let singleFileName = '';
+      if (fs.existsSync(path) && !fs.statSync(path).isDirectory()) {
+        isSingleFile = true;
+        parentDir = dir.dirname(path);
+        singleFileName = path.split('/').pop();
+      }
+
       // 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) {
@@ -114,6 +150,7 @@ class UnderpostFileStorage {
 
         if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
 
+        // Storage is canonical: persist the removal before any (optional) git tracking runs.
         Underpost.fs.writeStorageConf(storage, storageConf);
 
         if (associatedPaths.length === 0)
@@ -125,22 +162,31 @@ class UnderpostFileStorage {
           });
 
         if (options.git === true) {
-          const gitPath = hasPathFilter ? basePath : '.';
-          shellExec(`cd ${gitPath} && git add .`);
-          shellExec(`underpost cmt ${gitPath} feat`, {
-            silentOnError: true,
-            silent: true,
-            disableLog: true,
-          });
+          const gitPath = !hasPathFilter ? '.' : isSingleFile ? parentDir : basePath;
+          Underpost.fs.gitTrack(gitPath);
         }
 
         return;
       }
 
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
+      // For single files, run getDeleteFiles against the parent directory to avoid
+      // trying to `cd` into a file.
+      const gitContextPath = isSingleFile ? parentDir : path;
+      // Detecting locally-deleted files is a best-effort enhancement backed by git; if the path is
+      // not a repo (or git is unavailable) it must not block the canonical storage workflow.
+      let deleteFiles = [];
+      if (options.pull !== true) {
+        try {
+          deleteFiles = Underpost.repo.getDeleteFiles(gitContextPath);
+        } catch (error) {
+          logger.warn('delete detection skipped (git unavailable)', { path: gitContextPath, error: error?.message });
+        }
+      }
+
+      // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
-        const _path = path + '/' + relativePath;
-        if (_path in storage) {
+        const _path = isSingleFile ? (relativePath === singleFileName ? path : null) : path + '/' + relativePath;
+        if (_path && _path in storage) {
           await Underpost.fs.delete(_path);
           delete storage[_path];
         }
@@ -156,18 +202,21 @@ class UnderpostFileStorage {
         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"`, {
-            silentOnError: true,
-          });
-        }
+        if (options.git === true) Underpost.fs.gitTrack(gitContextPath, { init: true, message: 'Base pull state' });
       } else {
-        const files =
-          options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
+        let files;
+        if (isSingleFile) {
+          // Single file: treat the file itself as the sole item to process
+          files = [singleFileName];
+        } else {
+          files =
+            options.git === true
+              ? Underpost.repo.getChangedFiles(gitContextPath)
+              : await fs.readdir(path, { recursive: true });
+        }
         for (const relativePath of files) {
-          const _path = path + '/' + relativePath;
-          if (fs.statSync(_path).isDirectory()) {
+          const _path = isSingleFile ? path : path + '/' + relativePath;
+          if (fs.existsSync(_path) && fs.statSync(_path).isDirectory()) {
             if (options.pull === true && !fs.existsSync(_path)) fs.mkdirSync(_path, { recursive: true });
             continue;
           } else if (!(_path in storage) || options.force === true) {
@@ -176,15 +225,9 @@ class UnderpostFileStorage {
           } else logger.warn('File already exists', _path);
         }
       }
+      // Storage is canonical and always persisted; git is an optional layer on top.
       Underpost.fs.writeStorageConf(storage, storageConf);
-      if (options.git === true) {
-        shellExec(`cd ${path} && git add .`);
-        shellExec(`underpost cmt ${path} feat`, {
-          silentOnError: true,
-          silent: true,
-          disableLog: true,
-        });
-      }
+      if (options.git === true) Underpost.fs.gitTrack(gitContextPath);
     },
     /**
      * @method callback
@@ -206,10 +249,12 @@ class UnderpostFileStorage {
       path,
       options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
-      if (options.recursive === true || options.git === true)
+      // rm always routes through recursiveCallback so storage.*.json is updated regardless of
+      // --recursive/--git. The bare `delete` primitive only removes the remote asset and would
+      // otherwise leave the tracked storage key orphaned.
+      if (options.recursive === true || options.git === true || options.rm === true)
         return await Underpost.fs.recursiveCallback(path, options);
       if (options.pull === true) return await Underpost.fs.pull(path, options);
-      if (options.rm === true) return await Underpost.fs.delete(path, options);
       return await Underpost.fs.upload(path, options);
     },
     /**

package/src/cli/image.js

@@ -5,9 +5,12 @@
  */
 
 import fs from 'fs-extra';
+import os from 'os';
+import nodePath from 'path';
+import crypto from 'crypto';
 import { loggerFactory } from '../server/logger.js';
 import Underpost from '../index.js';
-import { getNpmRootPath, getUnderpostRootPath } from '../server/conf.js';
+import { getNpmRootPath } from '../server/conf.js';
 import { shellExec } from '../server/process.js';
 
 const logger = loggerFactory(import.meta);
@@ -23,59 +26,32 @@ class UnderpostImage {
   static API = {
     /**
      * @method pullBaseImages
-     * @description Pulls base images and builds a 'rockylinux9-underpost' image,
-     * then loads it into the specified Kubernetes cluster type (Kind, Kubeadm, or K3s).
-     * @param {object} options - Options for pulling and loading images.
-     * @param {boolean} [options.kind=false] - If true, load image into Kind cluster.
-     * @param {boolean} [options.kubeadm=false] - If true, load image into Kubeadm cluster.
-     * @param {boolean} [options.k3s=false] - If true, load image into K3s cluster.
-     * @param {string} [options.path=''] - Path to the Dockerfile context.
-     * @param {boolean} [options.dev=false] - If true, use development mode.
-     * @param {string} [options.version=''] - Version tag for the image.
-     * @param {string} [options.imageName=''] - Custom name for the image.
+     * @description Ensures the base image prerequisites for the runtime Dockerfiles
+     * are present on the host (currently `docker.io/rockylinux/rockylinux:9`). This
+     * only pulls — it does NOT build. Builds run with `podman build --pull=never`,
+     * so the base must exist locally beforehand; that is the sole purpose of this
+     * step. Combine with `--build` in the same command to pull-then-build.
      * @memberof UnderpostImage
      */
-    pullBaseImages(
-      options = {
-        kind: false,
-        kubeadm: false,
-        k3s: false,
-        path: '',
-        dev: false,
-        version: '',
-        imageName: '',
-      },
-    ) {
-      shellExec(`sudo podman pull docker.io/library/rockylinux:9`);
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      const baseCommandOption = options.dev ? ' --dev' : '';
-      const IMAGE_NAME = options.imageName
-        ? `options.imageName${options.version ? `:${options.version}` : ''}`
-        : `rockylinux9-underpost:${options.version ? options.version : Underpost.version}`;
-      let LOAD_TYPE = '';
-      if (options.kind === true) LOAD_TYPE = `--kind`;
-      else if (options.kubeadm === true) LOAD_TYPE = `--kubeadm`;
-      else if (options.k3s === true) LOAD_TYPE = `--k3s`;
-      shellExec(
-        `${baseCommand} image${baseCommandOption} --build --podman-save --reset --image-path=. --path ${
-          options.path ? options.path : getUnderpostRootPath()
-        } --image-name=${IMAGE_NAME} ${LOAD_TYPE}`,
-      );
+    pullBaseImages() {
+      shellExec(`sudo podman pull docker.io/rockylinux/rockylinux:9`);
     },
     /**
      * @method build
      * @description Builds a Docker image using Podman, optionally saves it as a tar archive,
-     * and loads it into a specified Kubernetes cluster (Kind, Kubeadm, or K3s).
+     * and loads it into a specified target (Kind, Kubeadm, or K3s cluster, or the local
+     * Docker store for Docker Compose).
      * @param {object} options - Options for building and loading images.
      * @param {string} [options.path=''] - The path to the directory containing the Dockerfile.
      * @param {string} [options.imageName=''] - The name and tag for the image (e.g., 'my-app:latest').
      * @param {string} [options.version=''] - Version tag for the image.
-     * @param {string} [options.imagePath=''] - Directory to save the image tar file.
+     * @param {string} [options.imageOutPath=''] - Directory to save the image tar file.
      * @param {string} [options.dockerfileName=''] - Name of the Dockerfile (defaults to 'Dockerfile').
      * @param {boolean} [options.podmanSave=false] - If true, save the image as a tar archive using Podman.
      * @param {boolean} [options.kind=false] - If true, load the image archive into a Kind cluster.
      * @param {boolean} [options.kubeadm=false] - If true, load the image archive into a Kubeadm cluster (uses 'ctr').
      * @param {boolean} [options.k3s=false] - If true, load the image archive into a K3s cluster (uses 'k3s ctr').
+     * @param {boolean} [options.dockerCompose=false] - If true, load the image archive into the local Docker store for Docker Compose.
      * @param {boolean} [options.reset=false] - If true, perform a no-cache build.
      * @param {boolean} [options.dev=false] - If true, use development mode.
      * @memberof UnderpostImage
@@ -85,42 +61,144 @@ class UnderpostImage {
         path: '',
         imageName: '',
         version: '',
-        imagePath: '',
+        imageOutPath: '',
         dockerfileName: '',
         podmanSave: false,
         kind: false,
         kubeadm: false,
         k3s: false,
+        dockerCompose: false,
         reset: false,
         dev: false,
       },
     ) {
-      let { path, imageName, version, imagePath, dockerfileName, podmanSave, kind, kubeadm, k3s, reset, dev } = options;
+      let {
+        path,
+        imageName,
+        version,
+        imageOutPath,
+        dockerfileName,
+        podmanSave,
+        kind,
+        kubeadm,
+        k3s,
+        dockerCompose,
+        reset,
+        dev,
+      } = options;
       if (!path) path = '.';
       if (!imageName) imageName = `rockylinux9-underpost:${Underpost.version}`;
-      if (!imagePath) imagePath = '.';
+      if (!imageOutPath) imageOutPath = '.';
       if (imageName.match('/')) imageName = imageName.split('/')[1];
       if (!version) version = 'latest';
       version = imageName && imageName.match(':') ? '' : `:${version}`;
       const podManImg = `localhost/${imageName}${version}`;
-      if (imagePath && typeof imagePath === 'string' && !fs.existsSync(imagePath))
-        fs.mkdirSync(imagePath, { recursive: true });
-      const tarFile = `${imagePath}/${imageName.replace(':', '_')}.tar`;
+      if (imageOutPath && typeof imageOutPath === 'string' && !fs.existsSync(imageOutPath))
+        fs.mkdirSync(imageOutPath, { recursive: true });
+      const tarFile = `${imageOutPath}/${imageName.replace(':', '_')}.tar`;
       let cache = '';
       if (reset === true) cache += ' --rm --no-cache';
+
+      // Forward GitHub credentials from the host environment into the build as
+      // podman/BuildKit secrets (`--secret id=...,src=...`), matching the
+      // `RUN --mount=type=secret,id=github_*` contract in the runtime
+      // Dockerfiles (e.g. src/runtime/engine-cyberia). Secrets are written to
+      // short-lived 0600 temp files and removed right after the build — they are
+      // never passed as build-args (which would persist in image history) nor
+      // baked into any layer.
+      const secretTmpFiles = [];
+      const secretFlags = [];
+      const addBuildSecret = (id, value) => {
+        if (!value) return;
+        const file = nodePath.join(os.tmpdir(), `underpost-secret-${id}-${crypto.randomBytes(6).toString('hex')}`);
+        fs.writeFileSync(file, String(value), { mode: 0o600 });
+        secretTmpFiles.push(file);
+        secretFlags.push(`--secret id=${id},src=${file}`);
+      };
+      // addBuildSecret('github_token', process.env.GITHUB_TOKEN);
+      addBuildSecret('github_username', process.env.GITHUB_USERNAME);
+      // Cloudinary creds power build-time asset pulls (`node bin fs --pull`).
+      // addBuildSecret('cloudinary_cloud_name', process.env.CLOUDINARY_CLOUD_NAME);
+      // addBuildSecret('cloudinary_api_key', process.env.CLOUDINARY_API_KEY);
+      // addBuildSecret('cloudinary_api_secret', process.env.CLOUDINARY_API_SECRET);
+      const secretArgs = secretFlags.length ? ` ${secretFlags.join(' ')}` : '';
+      if (secretFlags.length)
+        logger.info('Passing host GitHub credentials as build secrets', { ids: secretFlags.length });
+
       if (path)
-        shellExec(
-          `cd ${path} && sudo podman build -f ./${
-            dockerfileName && typeof dockerfileName === 'string' ? dockerfileName : 'Dockerfile'
-          } -t ${imageName} --pull=never --cap-add=CAP_AUDIT_WRITE${cache} --network host`,
-        );
-      if (podmanSave === true) {
+        try {
+          shellExec(
+            `cd ${path} && sudo podman build -f ./${
+              dockerfileName && typeof dockerfileName === 'string' ? dockerfileName : 'Dockerfile'
+            } -t ${imageName} --pull=never --cap-add=CAP_AUDIT_WRITE${cache}${secretArgs} --network host`,
+          );
+        } finally {
+          for (const file of secretTmpFiles) {
+            try {
+              fs.removeSync(file);
+            } catch {
+              /* best-effort cleanup */
+            }
+          }
+        }
+      // Loading into any target requires the tar archive, so imply the save when
+      // one is set (kind/kubeadm/k3s/docker-compose) even if --podman-save was omitted.
+      const loadTarget = kind === true || kubeadm === true || k3s === true || dockerCompose === true;
+      if (podmanSave === true || loadTarget) {
         if (fs.existsSync(tarFile)) fs.removeSync(tarFile);
         shellExec(`podman save -o ${tarFile} ${podManImg}`);
       }
       if (kind === true) shellExec(`sudo kind load image-archive ${tarFile}`);
       else if (kubeadm === true) shellExec(`sudo ctr -n k8s.io images import ${tarFile}`);
       else if (k3s === true) shellExec(`sudo k3s ctr images import ${tarFile}`);
+      // Independent of any cluster target: make the local image available to the
+      // Docker daemon so `docker compose` can resolve it (e.g. ENGINE_CYBERIA_IMAGE).
+      if (dockerCompose === true) shellExec(`sudo docker load -i ${tarFile}`);
+    },
+    /**
+     * @method importTar
+     * @description Loads a pre-built image tar archive into each enabled target
+     * without building anything. Mirrors the load step of {@link build}, but
+     * the archive is supplied directly via `--import-tar <tar-path>` and every
+     * enabled target flag is honored (the same archive is loaded into each), so
+     * `--kind --docker-compose` loads it into both.
+     * @param {object} options - CLI options.
+     * @param {string} options.importTar - Path to the image tar archive (e.g. `./image-v1.0.0.tar`).
+     * @param {boolean} [options.kind] - Load into the Kind cluster (`kind load image-archive`).
+     * @param {boolean} [options.kubeadm] - Import into kubeadm containerd (`ctr -n k8s.io images import`).
+     * @param {boolean} [options.k3s] - Import into k3s containerd (`k3s ctr images import`).
+     * @param {boolean} [options.dockerCompose] - Load into the local Docker daemon (`docker load`) for Docker Compose.
+     * @returns {void}
+     * @memberof UnderpostImage
+     */
+    importTar(options = { importTar: '', kind: false, kubeadm: false, k3s: false, dockerCompose: false }) {
+      const { importTar, kind, kubeadm, k3s, dockerCompose } = options;
+      if (!importTar || typeof importTar !== 'string' || !fs.existsSync(importTar)) {
+        logger.error('image --import-tar: archive not found', { importTar });
+        return;
+      }
+      const targets = [];
+      if (kind === true) {
+        shellExec(`sudo kind load image-archive ${importTar}`);
+        targets.push('kind');
+      }
+      if (kubeadm === true) {
+        shellExec(`sudo ctr -n k8s.io images import ${importTar}`);
+        targets.push('kubeadm');
+      }
+      if (k3s === true) {
+        shellExec(`sudo k3s ctr images import ${importTar}`);
+        targets.push('k3s');
+      }
+      if (dockerCompose === true) {
+        shellExec(`sudo docker load -i ${importTar}`);
+        targets.push('docker-compose');
+      }
+      if (targets.length === 0)
+        logger.warn(
+          'image --import-tar: no target enabled; combine with --kind, --kubeadm, --k3s and/or --docker-compose',
+        );
+      else logger.info('image --import-tar: archive loaded', { importTar, targets });
     },
     /**
      * @method getCurrentLoaded

package/src/cli/index.js

@@ -110,16 +110,18 @@ program
   .option('--cached', 'Commit staged changes only or context.')
   .option('--hashes <hashes>', 'Comma-separated list of specific file hashes of commits.')
   .option('--extension <extension>', 'specific file extensions of commits.')
-  .option(
-    '--changelog [latest-n]',
-    'Print plain the changelog of the specified number of latest n commits, if no number is provided it will get the changelog to latest ci integration',
-  )
+  .option('--changelog', 'Print the plain changelog of the last N commits (see --from-n-commit, default 1).')
   .option('--changelog-build', 'Builds a CHANGELOG.md file based on the commit history')
   .option('--changelog-min-version <version>', 'Sets the minimum version limit for --changelog-build (default: 2.85.0)')
   .option(
     '--changelog-no-hash',
     'Excludes commit hashes from the generated changelog entries (used with --changelog-build).',
   )
+  .option(
+    '--changelog-msg',
+    'Print the sanitized, commit-ready changelog message of the last N commits (see --from-n-commit, default 1). Empty when there are no tagged entries.',
+  )
+  .option('--from-n-commit <n>', 'Number of latest commits to include in --changelog/--changelog-msg (default: 1).')
   .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.')
@@ -132,6 +134,12 @@ program
     '--has-changes',
     'Prints "1" if there are staged or unstaged git changes in the repository, empty string otherwise.',
   )
+  .option('--remote-url', 'Prints the current git remote URL (origin) in plain text.')
+  .option(
+    '--switch-repo <url>',
+    'Switches the git remote (origin) to <url> and force-pulls the target branch, overwriting the current working tree (discards local commits and tracked changes). Accepts a full URL or "owner/repo".',
+  )
+  .option('--target-branch <branch>', 'Target branch for --switch-repo (default: master).')
   .description('Manages commits to a GitHub repository, supporting various commit types and options.')
   .action(Underpost.repo.commit);
 
@@ -330,6 +338,10 @@ program
       'Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer.',
   )
   .option('--node <node>', 'Sets optional node for deployment operations.')
+  .option(
+    '--ssh-key-path <path>',
+    'Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa.',
+  )
   .option(
     '--build-manifest',
     'Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets.',
@@ -424,25 +436,31 @@ program
   .option('--rm <image-id>', 'Removes specified Underpost Dockerfile images.')
   .option('--path [path]', 'The path to the Dockerfile directory.')
   .option('--image-name [image-name]', 'Sets a custom name for the Docker image.')
-  .option('--image-path [image-path]', 'Sets the output path for the tar image archive.')
+  .option('--image-out-path [image-out-path]', 'Sets the output path for the tar image archive.')
   .option('--dockerfile-name [dockerfile-name]', 'Sets a custom name for the Dockerfile.')
   .option('--podman-save', 'Exports the built image as a tar file using Podman.')
-  .option('--pull-base', 'Pulls base images and builds a "rockylinux9-underpost" image.')
+  .option('--pull-base', 'Pulls the base image prerequisites (rockylinux:9) on the host; combine with --build.')
   .option('--spec', 'Get current cached list of container images used by all pods')
   .option('--namespace <namespace>', 'Kubernetes namespace for image operations (defaults to "default").')
   .option('--kind', 'Set kind cluster env image context management.')
   .option('--kubeadm', 'Set kubeadm cluster env image context management.')
   .option('--k3s', 'Set k3s cluster env image context management.')
+  .option('--docker-compose', 'Load the built image tar into the local Docker store for Docker Compose availability.')
   .option('--node-name', 'Set node name for kubeadm or k3s cluster env image context management.')
   .option('--reset', 'Performs a build without using the cache.')
   .option('--dev', 'Use development mode.')
   .option('--pull-dockerhub <dockerhub-image>', 'Sets a custom Docker Hub image for base image pulls.')
+  .option(
+    '--import-tar <tar-path>',
+    'Load a pre-built image tar archive (e.g. ./image-v1.0.0.tar) into the enabled target(s) without building. Combine with --kind, --kubeadm, --k3s and/or --docker-compose; the archive is loaded into each enabled one.',
+  )
   .description('Manages Docker images, including building, saving, and loading into Kubernetes clusters.')
   .action(async (options) => {
     if (options.rm) Underpost.image.rm({ ...options, imageName: options.rm });
     if (options.ls) Underpost.image.list({ ...options, log: true });
     if (options.pullBase) Underpost.image.pullBaseImages(options);
     if (options.build) Underpost.image.build(options);
+    if (options.importTar) Underpost.image.importTar(options);
     if (options.pullDockerhub)
       Underpost.image.pullDockerHubImage({ ...options, dockerhubImage: options.pullDockerhub });
   });
@@ -630,6 +648,10 @@ program
   .option('--replicas <replicas>', 'Sets a custom number of replicas for deployment.')
   .option('--pod-name <pod-name>', 'Optional: Specifies the pod name for execution.')
   .option('--node-name <node-name>', 'Optional: Specifies the node name for execution.')
+  .option(
+    '--ssh-key-path <path>',
+    'Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa.',
+  )
   .option('--port <port>', 'Optional: Specifies the port for execution.')
   .option('--etc-hosts', 'Enables etc-hosts context for the runner execution.')
   .option('--volume-host-path <volume-host-path>', 'Optional: Specifies the volume host path for test execution.')
@@ -678,6 +700,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('--traffic <traffic>', 'Blue/green traffic colour to bake into generated manifests (default: blue).')
   .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.')
@@ -738,6 +761,43 @@ program
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
+program
+  .command('docker-compose')
+  .argument('[target]', 'Optional service name for --logs, --shell, --restart, or --build.')
+  .option('--install', 'Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts.')
+  .option(
+    '--reset',
+    'Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts.',
+  )
+  .option('--force', 'Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset).')
+  .option(
+    '--deploy-id <deploy-id>',
+    "Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js).",
+  )
+  .option(
+    '--docker-compose-id <docker-compose-id>',
+    'Selects a canonical custom-workflow stack at engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/ ' +
+      '(docker-compose.yml + compose.env + nginx.conf, used as-is; nginx/env generation is skipped). ' +
+      'e.g. --deploy-id dd-cyberia --docker-compose-id cyberia for the Cyberia MMO ecosystem.',
+  )
+  .option('--env <env>', 'Deployment environment for non-default deploy ids (default: development).')
+  .option('--generate', 'Render dynamic supporting files (nginx router config, env-file, app-command override).')
+  .option('--up', 'Start the full stack detached (regenerates config first).')
+  .option('--down', 'Stop and remove containers (and orphans).')
+  .option('--volumes', 'With --down, also remove named volumes (destroys persisted data).')
+  .option('--restart', 'Restart services (optionally a single [target]).')
+  .option('--build', 'With --up rebuild images; alone, rebuilds images with --no-cache.')
+  .option('--pull', 'Pull upstream images for all services.')
+  .option('--logs', 'Follow logs for all services (optionally a single [target]).')
+  .option('--status', 'Show a formatted status table of services.')
+  .option('--shell', 'Open an interactive shell in [target] (default: app).')
+  .option('--exec <subcommand>', 'General-purpose passthrough docker compose subcommand.')
+  .option('--compose-file <path>', 'Path to the compose file (default: docker-compose.yml).')
+  .option('--env-file <path>', 'Path to the compose env-file (default: docker/compose.env).')
+  .option('--nginx-conf <path>', 'Path to the generated nginx config (default: docker/nginx/default.conf).')
+  .description('General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).')
+  .action(Underpost.dockerCompose.callback);
+
 program
   .command('lxd')
   .argument(
@@ -856,6 +916,42 @@ program
   .option('--remove-machines <system-ids>', 'Removes baremetal machines by comma-separated system IDs, or use "all"')
   .option('--clear-discovered', 'Clears all discovered baremetal machines from the database.')
   .option('--commission', 'Init workflow for commissioning a physical machine.')
+  .option(
+    '--install-disk [device]',
+    'Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk.',
+  )
+  .option(
+    '--no-auto-install',
+    'Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install).',
+  )
+  .option('--no-remote-install', 'Skips the controller-side remote install orchestration over SSH.')
+  .option(
+    '--worker',
+    'Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane.',
+  )
+  .option('--control <ip>', 'Control-plane IP the worker node joins (used with --worker for kubeadm infra setup).')
+  .option(
+    '--ssh-key-dir <dir>',
+    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~.',
+  )
+  .option(
+    '--deploy-id <deploy-id>',
+    'Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command.',
+  )
+  .option(
+    '--user <user>',
+    'SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user.',
+  )
+  .option(
+    '--engine-repo <url>',
+    'Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine).',
+  )
+  .option('--engine-branch <branch>', 'Branch of the engine repo to clone on the node.')
+  .option(
+    '--engine-private-repo <url>',
+    'Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private).',
+  )
+  .option('--engine-private-branch <branch>', 'Branch of the engine-private repo to clone on the node.')
   .option(
     '--bootstrap-http-server-run',
     'Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning.',
@@ -896,6 +992,14 @@ program
   )
   .option('--dev', 'Sets the development context environment for baremetal operations.')
   .option('--ls', 'Lists available boot resources and machines.')
+  .option(
+    '--resume-infra-setup',
+    'Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH.',
+  )
+  .option(
+    '--resume-join',
+    'Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join.',
+  )
   .description(
     'Manages baremetal server operations, including installation, database setup, commissioning, and user management.',
   )