underpost 3.2.30 → 3.2.80

package/src/cli/docker-compose.js

@@ -12,6 +12,7 @@ import fs from 'fs-extra';
 import nodePath from 'path';
 import { getRootDirectory, shellExec } from '../server/process.js';
 import { loggerFactory } from '../server/logger.js';
+import { loadInstanceTopology } from '../server/conf.js';
 import Nginx from '../runtime/nginx/Nginx.js';
 
 const logger = loggerFactory(import.meta);
@@ -77,14 +78,42 @@ class UnderpostDockerCompose {
     return nodePath.isAbsolute(relPath) ? relPath : nodePath.join(getRootDirectory(), relPath);
   }
 
+  /**
+   * Resolves the canonical directory for a custom docker-compose workflow,
+   * keyed by `--deploy-id` + `--docker-compose-id`:
+   * `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>`.
+   * This directory ships its own `docker-compose.yml`, `compose.env`, and
+   * `nginx.conf` (used as-is, never generated). Returns null when
+   * `--docker-compose-id` is not set (the default, self-generating workflow).
+   * @param {object} options - CLI options.
+   * @returns {string|null} Repo-root-relative canonical dir, or null.
+   * @memberof UnderpostDockerCompose
+   */
+  static composeIdBase(options = {}) {
+    if (!options.dockerComposeId) return null;
+    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
+    return `engine-private/conf/${deployId}/docker-compose/${options.dockerComposeId}`;
+  }
+
   /**
    * Builds the base `docker compose` invocation with explicit file and env-file,
    * so behavior is independent of the caller's working directory.
+   *
+   * Custom workflow (`--docker-compose-id`): the compose file, env-file, and
+   * bind-mounted config (nginx.conf, mongodb/) all live in the canonical dir, so
+   * compose runs with `--project-directory` pinned there and no app-override.
    * @param {object} options - CLI options.
    * @returns {string} The base command string (without a subcommand).
    * @memberof UnderpostDockerCompose
    */
   static baseCmd(options = {}) {
+    const base = UnderpostDockerCompose.composeIdBase(options);
+    if (base) {
+      const projectDir = UnderpostDockerCompose.resolve(base);
+      const composeFile = UnderpostDockerCompose.resolve(options.composeFile || `${base}/docker-compose.yml`);
+      const envFile = UnderpostDockerCompose.resolve(options.envFile || `${base}/compose.env`);
+      return `docker compose --project-directory ${projectDir} --env-file ${envFile} -f ${composeFile}`;
+    }
     const composeFile = UnderpostDockerCompose.resolve(options.composeFile || 'docker-compose.yml');
     const envFile = UnderpostDockerCompose.resolve(options.envFile || 'docker/compose.env');
     const overrideFile = UnderpostDockerCompose.resolve(options.appOverride || 'docker/compose.app.yml');
@@ -163,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.22
+APP_TAG=v3.2.80
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest
@@ -333,6 +362,150 @@ datasources:
 `;
   }
 
+  /**
+   * Expands the deploy's `multiInstance` topology (from conf.instances.json, via
+   * {@link loadInstanceTopology}) into the per-variant descriptors the compose
+   * generators consume. Application-agnostic: it only reads variant code/slug/
+   * path and the default code. Returns null when the deploy is single-instance.
+   * @param {object} options - CLI options.
+   * @returns {?{defaultCode: string, variants: Array<object>}}
+   * @memberof UnderpostDockerCompose
+   */
+  static instanceTopology(options = {}) {
+    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
+    let topology = null;
+    try {
+      topology = loadInstanceTopology(deployId);
+    } catch {
+      return null;
+    }
+    if (!topology || !Array.isArray(topology.variants) || topology.variants.length === 0) return null;
+    const defaultCode = topology.default || topology.variants[0].code;
+    const variants = topology.variants.map((v) => {
+      const path = v.path || '/';
+      const isDefault = !(v.slug || '');
+      return {
+        code: v.code,
+        slug: v.slug || '',
+        path,
+        isDefault,
+        // Service/container suffix: empty for the default variant so it keeps
+        // the historic `cyberia-server` / `cyberia-client` names (and their
+        // published host ports); `-forest`, `-test`, … for the rest.
+        suffix: v.slug ? `-${v.slug}` : '',
+        // Backend prefix strip, mirroring the K8s pathRewritePolicy: the Go
+        // server serves `/ws` at its root, so a `/FOREST` prefix is stripped.
+        strip: path !== '/',
+      };
+    });
+    return { defaultCode, variants };
+  }
+
+  /**
+   * Renders the nginx reverse-proxy config for the multi-instance Cyberia stack
+   * as a SINGLE localhost gateway (dev compose is single-host; production uses
+   * the K8s HTTPProxy, not this file). All three tiers share one origin, routed
+   * by URL sub-path so `http://localhost/` works with no /etc/hosts:
+   *   /api/*, /assets/*        -> engine-cyberia (shared content authority)
+   *   /<slug>/ws               -> cyberia-server-<slug>  (prefix stripped; the Go
+   *                               runtime is instance-agnostic, selected by
+   *                               INSTANCE_CODE), and /ws -> the default server
+   *   /<slug>, /               -> cyberia-client-<slug>  (prefix kept; the WASM
+   *                               reads the instance from the URL)
+   * Upstreams resolve lazily through Docker's embedded DNS so a variant that is
+   * briefly down never fails nginx startup. Returns null for single-instance.
+   * @param {object} options - CLI options.
+   * @returns {?string} nginx.conf content, or null.
+   * @memberof UnderpostDockerCompose
+   */
+  static instancesNginxContent(options = {}) {
+    const topology = UnderpostDockerCompose.instanceTopology(options);
+    if (!topology) return null;
+    const { variants } = topology;
+
+    const headers = `            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_read_timeout 3600s;`;
+
+    const proxyBlock = (variable, upstream, extra = '') =>
+      `            set ${variable} ${upstream};
+${extra}            proxy_pass http://${variable};
+${headers}`;
+
+    // Websocket tier: /<path>/ws -> server (prefix stripped); default -> = /ws.
+    // Longest-prefix ensures /<path>/ws beats the /<path> client location.
+    const wsLocations = variants
+      .map((v) => {
+        const upstream = `cyberia-server${v.suffix}:8081`;
+        const varName = `$up_server_${v.slug || 'default'}`;
+        if (v.isDefault) return `        location = /ws {\n${proxyBlock(varName, upstream)}\n        }`;
+        return `        location ${v.path}/ws {\n${proxyBlock(
+          varName,
+          upstream,
+          `            rewrite ^${v.path}/(.*)$ /$1 break;\n`,
+        )}\n        }`;
+      })
+      .join('\n\n');
+
+    // Presentation tier: /<path> -> client (prefix kept); default -> catch-all /.
+    const clientLocations = variants
+      .map((v) => {
+        const upstream = `cyberia-client${v.suffix}:8081`;
+        const varName = `$up_client_${v.slug || 'default'}`;
+        if (v.isDefault) return `        location / {\n${proxyBlock(varName, upstream)}\n        }`;
+        return `        location = ${v.path} { return 301 ${v.path}/; }
+        location ${v.path} {\n${proxyBlock(varName, upstream)}\n        }`;
+      })
+      .join('\n\n');
+
+    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
+    return `# Generated by 'underpost docker-compose --generate --deploy-id ${deployId} --docker-compose-id ${options.dockerComposeId || 'cyberia'}' — do not hand-edit.
+# Source of truth: engine-private/conf/${deployId}/conf.instances.json (multiInstance).
+# Single localhost gateway (dev compose). Access http://localhost/ (default),
+# http://localhost/<PATH> per variant. Client origins point back here
+# (compose.env CYBERIA_WS_ORIGIN=ws://localhost, CYBERIA_ENGINE_API_ORIGIN=http://localhost).
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+# Docker embedded DNS: resolve upstream names per request so a variant that is
+# briefly down never fails nginx startup or config reload.
+resolver 127.0.0.11 ipv6=off valid=10s;
+
+proxy_http_version 1.1;
+
+server {
+    listen 80 default_server;
+    server_name localhost 127.0.0.1 _;
+
+        location = /healthz {
+            access_log off;
+            return 200 "ok\\n";
+            add_header Content-Type text/plain;
+        }
+
+        # Shared content authority: REST API + engine-served assets (fonts, ui-icons).
+        location /api/ {
+${proxyBlock('$up_engine', 'engine-cyberia:4005')}
+        }
+
+        location /assets/ {
+${proxyBlock('$up_engine', 'engine-cyberia:4005')}
+        }
+
+${wsLocations}
+
+${clientLocations}
+}
+`;
+  }
+
   /**
    * Renders all dynamic supporting files: the nginx reverse-proxy config (from
    * PROXY_HOSTS), the monitoring configs (Prometheus + Grafana datasource), and
@@ -343,6 +516,28 @@ datasources:
    * @memberof UnderpostDockerCompose
    */
   static generate(options = {}) {
+    // Custom workflow: docker-compose.yml and compose.env are hand-authored in
+    // the canonical dir and used as-is — do NOT generate them. Only (re)write
+    // the two generated artifacts: the MongoDB entrypoint (replica-set
+    // bootstrap) and, for a multi-instance deploy, nginx.conf (per-variant
+    // sub-path routing derived from the conf.instances.json multiInstance block,
+    // kept in sync with the service tiers hand-authored in docker-compose.yml).
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      fs.mkdirpSync(nodePath.dirname(mongoEntrypointPath));
+      fs.writeFileSync(mongoEntrypointPath, UnderpostDockerCompose.mongoEntrypointContent(), { mode: 0o755 });
+      logger.info('mongodb entrypoint written (custom workflow)', { path: mongoEntrypointPath });
+
+      const nginx = UnderpostDockerCompose.instancesNginxContent(options);
+      if (nginx) {
+        const nginxPath = UnderpostDockerCompose.resolve(`${composeIdBase}/nginx.conf`);
+        fs.writeFileSync(nginxPath, nginx, 'utf8');
+        logger.info('multi-instance nginx.conf written', { path: nginxPath });
+      }
+      return;
+    }
+
     Nginx.removeRouter();
     for (const { host, routes } of PROXY_HOSTS) Nginx.createApp({ host, routes });
     Nginx.createDefaultServer(DEFAULT_UPSTREAM);
@@ -449,6 +644,21 @@ datasources:
       silentOnError: true,
     });
 
+    // Custom workflow: docker-compose.yml and compose.env are hand-authored
+    // source — never prune them. Drop only the generated mongo entrypoint;
+    // nginx.conf is left in place so the mount stays valid and --generate/--up
+    // rewrites it.
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      if (fs.existsSync(mongoEntrypointPath)) {
+        fs.removeSync(mongoEntrypointPath);
+        logger.info('removed generated artifact', { path: mongoEntrypointPath });
+      }
+      logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
+      return;
+    }
+
     // Phase 2: prune generated artifacts (regenerated on the next --generate/--up).
     const artifacts = options.force
       ? [...GENERATED_ARTIFACTS, options.envFile || 'docker/compose.env']
@@ -489,6 +699,7 @@ datasources:
      * @param {boolean} [options.shell] - Open an interactive shell in `target` (default: app).
      * @param {string} [options.exec] - General-purpose passthrough docker compose subcommand.
      * @param {string} [options.deployId] - Deployment to run as the app (default: dd-default). `dd-default` self-bootstraps a fresh engine; any other id runs the standard `underpost start` command.
+     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/` (docker-compose.yml + compose.env + nginx.conf, used as-is), skipping nginx/env/app-override generation. Used by the Cyberia MMO ecosystem (`--deploy-id dd-cyberia --docker-compose-id cyberia`).
      * @param {string} [options.env] - Deployment environment for non-default deploy ids (default: development).
      * @param {string} [options.composeFile] - Override compose file path.
      * @param {string} [options.envFile] - Override env-file path.

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.
@@ -125,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)
@@ -136,13 +162,8 @@ 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;
@@ -151,7 +172,16 @@ class UnderpostFileStorage {
       // For single files, run getDeleteFiles against the parent directory to avoid
       // trying to `cd` into a file.
       const gitContextPath = isSingleFile ? parentDir : path;
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(gitContextPath);
+      // 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) {
@@ -172,12 +202,7 @@ 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: gitContextPath });
-          shellExec(`cd ${gitContextPath} && 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 {
         let files;
         if (isSingleFile) {
@@ -200,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 ${gitContextPath} && git add .`);
-        shellExec(`underpost cmt ${gitContextPath} feat`, {
-          silentOnError: true,
-          silent: true,
-          disableLog: true,
-        });
-      }
+      if (options.git === true) Underpost.fs.gitTrack(gitContextPath);
     },
     /**
      * @method callback
@@ -230,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);
     },
     /**
@@ -294,7 +315,6 @@ class UnderpostFileStorage {
         public_ids: [path],
         resource_type: 'raw',
       });
-      logger.info('download result', downloadResult);
       await Downloader.downloadFile(downloadResult, zipPath);
 
       if (options.omitUnzip === true) {

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,162 @@ 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);
+      // Build secrets are created dynamically: each `RUN --mount=type=secret,id=<x>`
+      // id maps to a host env var; only the ones actually set are passed, so a
+      // Dockerfile that omits (or comments out) a mount just never sees it. Extend
+      // this map — plus a merge of any caller-supplied `options.buildSecrets` — to
+      // add more without touching the call sites. Secrets never persist in image
+      // history (unlike build-args); they live in 0600 temp files removed post-build.
+      const BUILD_SECRET_ENV = {
+        //   // Cloudinary creds power build-time asset pulls (`node bin fs --pull`).
+        //   cloudinary_cloud_name: 'CLOUDINARY_CLOUD_NAME',
+        //   cloudinary_api_key: 'CLOUDINARY_API_KEY',
+        //   cloudinary_api_secret: 'CLOUDINARY_API_SECRET',
+      };
+      for (const [id, envVar] of Object.entries(BUILD_SECRET_ENV)) addBuildSecret(id, process.env[envVar]);
+      for (const [id, value] of Object.entries(options.buildSecrets || {})) addBuildSecret(id, value);
+      const secretArgs = secretFlags.length ? ` ${secretFlags.join(' ')}` : '';
+      if (secretFlags.length) logger.info('Passing host credentials as build secrets', { ids: secretFlags.length });
+
+      // Non-secret build args (e.g. INSTANCE_CODES for engine-cyberia): injected
+      // dynamically from `options.buildArgs`, overriding the Dockerfile's ARG
+      // defaults. Unlike secrets these DO persist in image metadata, so only
+      // non-sensitive values belong here.
+      const buildArgFlags = Object.entries(options.buildArgs || {})
+        .filter(([, v]) => v !== undefined && v !== null && v !== '')
+        .map(([k, v]) => `--build-arg ${k}=${JSON.stringify(String(v))}`);
+      const buildArgStr = buildArgFlags.length ? ` ${buildArgFlags.join(' ')}` : '';
+
       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}${buildArgStr} --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