underpost 3.2.70 → 3.2.80

package/src/api/file/file.router.js

@@ -1,12 +1,10 @@
+import express from 'express';
 import { adminGuard } from '../../server/auth.js';
-import { loggerFactory } from '../../server/logger.js';
 import { FileController } from './file.controller.js';
-import express from 'express';
-
-const logger = loggerFactory(import.meta);
 
 class FileRouter {
   /**
+   * authenticated writes, admin-only deletes.
    * @param {import('../types.js').RouterOptions} options
    * @returns {import('express').Router}
    */
@@ -17,8 +15,18 @@ class FileRouter {
     router.get(`/blob/:id`, async (req, res) => await FileController.get(req, res, options));
     router.get(`/:id`, async (req, res) => await FileController.get(req, res, options));
     router.get(`/`, async (req, res) => await FileController.get(req, res, options));
-    router.delete(`/:id`, options.authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
-    router.delete(`/`, options.authMiddleware, adminGuard, async (req, res) => await FileController.delete(req, res, options));
+    router.delete(
+      `/:id`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await FileController.delete(req, res, options),
+    );
+    router.delete(
+      `/`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await FileController.delete(req, res, options),
+    );
     return router;
   }
 }

package/src/api/test/test.controller.js

@@ -1,59 +1,14 @@
-import { loggerFactory } from '../../server/logger.js';
+import { controllerHandler, sendSuccess, serviceHandler } from '../../server/middlewares.js';
 import { TestService } from './test.service.js';
 
-const logger = loggerFactory(import.meta);
-
 class TestController {
-  static post = async (req, res, options) => {
-    try {
-      return res.status(200).json({
-        status: 'success',
-        data: await TestService.post(req, res, options),
-      });
-    } catch (error) {
-      logger.error(error, error.stack);
-      return res.status(400).json({
-        status: 'error',
-        message: error.message,
-      });
-    }
-  };
-  static get = async (req, res, options) => {
-    try {
-      const result = await TestService.get(req, res, options);
-      if (result)
-        return res.status(200).json({
-          status: 'success',
-          data: result,
-        });
-      else
-        return res.status(400).json({
-          status: 'error',
-        });
-    } catch (error) {
-      logger.error(error, error.stack);
-      return res.status(400).json({
-        status: 'error',
-        message: error.message,
-      });
-    }
-  };
-  static delete = async (req, res, options) => {
-    try {
-      const result = await TestService.delete(req, res, options);
-
-      return res.status(200).json({
-        status: 'success',
-        data: result,
-      });
-    } catch (error) {
-      logger.error(error, error.stack);
-      return res.status(400).json({
-        status: 'error',
-        message: error.message,
-      });
-    }
-  };
+  static post = serviceHandler(TestService.post);
+  static get = controllerHandler(async (req, res, options) => {
+    const result = await TestService.get(req, res, options);
+    if (result) return sendSuccess(res, result);
+    return res.status(400).json({ status: 'error' });
+  });
+  static delete = serviceHandler(TestService.delete);
 }
 
 export { TestController };

package/src/api/test/test.router.js

@@ -1,8 +1,5 @@
-import { loggerFactory } from '../../server/logger.js';
-import { TestController } from './test.controller.js';
 import express from 'express';
-
-const logger = loggerFactory(import.meta);
+import { TestController } from './test.controller.js';
 
 class TestRouter {
   /**

package/src/cli/cluster.js

@@ -902,10 +902,9 @@ net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-k3s.conf > /dev/null`,
         { silentOnError: true },
       );
       // Podman native — on this host images/overlays live under /var/lib/containers/storage.
-      shellExec(
-        `if command -v podman >/dev/null 2>&1; then sudo podman system prune ${a}--volumes -f; fi`,
-        { silentOnError: true },
-      );
+      shellExec(`if command -v podman >/dev/null 2>&1; then sudo podman system prune ${a}--volumes -f; fi`, {
+        silentOnError: true,
+      });
       if (options.crictl) {
         const ep = options.criSocket ? `--runtime-endpoint ${options.criSocket} ` : '';
         shellExec(
@@ -1198,13 +1197,34 @@ exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
 EOF`);
       shellExec(`sudo yum install -y kubelet kubeadm kubectl --disableexcludes=kubernetes`);
 
-      // Install Helm
-      shellExec(`curl -fsSL -o get_helm.sh https://cdn.jsdelivr.net/gh/helm/helm@main/scripts/get-helm-3`);
-      shellExec(`chmod 700 get_helm.sh`);
-      shellExec(`./get_helm.sh`);
-      shellExec(`chmod +x /usr/local/bin/helm`);
-      shellExec(`sudo mv /usr/local/bin/helm /bin/helm`);
-      shellExec(`sudo rm -rf get_helm.sh`);
+      // Install Helm — check if already installed and linked to /bin/helm first
+      const helmBin = shellExec(`test -x /bin/helm && echo exists || echo missing`, {
+        stdout: true,
+        silent: true,
+      }).trim();
+      const helmLocalBin = shellExec(`test -x /usr/local/bin/helm && echo exists || echo missing`, {
+        stdout: true,
+        silent: true,
+      }).trim();
+
+      if (helmBin === 'exists') {
+        logger.info('Helm is already installed and linked to /bin/helm; skipping.');
+      } else if (helmLocalBin === 'exists') {
+        // Helm binary exists at /usr/local/bin but not linked to /bin/helm
+        logger.info('Helm found at /usr/local/bin; linking to /bin/helm...');
+        shellExec(`sudo ln -sf /usr/local/bin/helm /bin/helm`);
+      } else {
+        // Helm not installed — download and install
+        shellExec(`curl -fsSL -o get_helm.sh https://cdn.jsdelivr.net/gh/helm/helm@main/scripts/get-helm-3`);
+        shellExec(`chmod 700 get_helm.sh`);
+        // Run get_helm.sh but ignore its exit code — it may fail on PATH check
+        // even when installation succeeds (binary placed at /usr/local/bin).
+        shellExec(`bash ./get_helm.sh || true`);
+        // Ensure the binary is executable and linked to /bin/helm
+        shellExec(`test -x /usr/local/bin/helm && sudo chmod +x /usr/local/bin/helm || true`);
+        shellExec(`test -x /usr/local/bin/helm && sudo ln -sf /usr/local/bin/helm /bin/helm || true`);
+        shellExec(`sudo rm -rf get_helm.sh`);
+      }
 
       // Install snap
       shellExec(`sudo yum install -y snapd`);

package/src/cli/db.js

@@ -6,7 +6,7 @@
  * Supports MariaDB and MongoDB with import/export capabilities, Git integration, and multi-pod operations.
  */
 
-import { mergeFile, splitFileFactory, loadConfServerJson, resolveConfSecrets } from '../server/conf.js';
+import { mergeFile, splitFileFactory, loadConfServerJson, resolveConfSecrets, loadConfInstances } from '../server/conf.js';
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
@@ -1119,7 +1119,9 @@ class UnderpostDB {
             // Process additional instances
             const confInstancesPath = `./engine-private/conf/${deployId}/conf.instances.json`;
             if (fs.existsSync(confInstancesPath)) {
-              const confInstances = JSON.parse(fs.readFileSync(confInstancesPath, 'utf8'));
+              // Expands multiInstance variants so each deployed instance is
+              // registered (handles both the bare-array and { instances } shapes).
+              const confInstances = loadConfInstances(deployId);
               for (const instance of confInstances) {
                 const { id, host, path, fromPort, metadata } = instance;
                 const { runtime } = metadata;

package/src/cli/deploy.js

@@ -12,6 +12,7 @@ import {
   cronDeployIdResolve,
   deployRangePortFactory,
   getDataDeploy,
+  loadConfInstances,
   loadConfServerJson,
   loadReplicas,
   pathPortAssignmentFactory,
@@ -22,8 +23,25 @@ import { INTERNAL_READY_PATH, INTERNAL_HEALTH_PATH } from '../server/runtime-sta
 import fs from 'fs-extra';
 import dotenv from 'dotenv';
 import os from 'node:os';
+import crypto from 'node:crypto';
 import Underpost from '../index.js';
 
+/**
+ * Clamps an identifier to the Kubernetes DNS-1123 label limit (63 chars),
+ * used for pod-local `volumes[].name` / `volumeMounts[].name`. Names within the
+ * limit are returned verbatim so existing short names are stable; longer ones
+ * are truncated and suffixed with an 8-char content hash to stay unique and
+ * deterministic (e.g. the per-variant instance volume names, which append the
+ * full `<deployId>-<env>-<traffic>` and can exceed 63).
+ * @param {string} name - Candidate name.
+ * @returns {string} A name no longer than 63 characters.
+ */
+const k8sVolumeName = (name) => {
+  if (typeof name !== 'string' || name.length <= 63) return name;
+  const hash = crypto.createHash('sha1').update(name).digest('hex').slice(0, 8);
+  return `${name.slice(0, 54)}-${hash}`;
+};
+
 const logger = loggerFactory(import.meta);
 
 /**
@@ -668,7 +686,7 @@ spec:
      * @returns {string|null} - Current traffic status ('blue' or 'green') or null if not found.
      * @memberof UnderpostDeploy
      */
-    getCurrentTraffic(deployId, options = { hostTest: '', namespace: '' }) {
+    getCurrentTraffic(deployId, options = { hostTest: '', namespace: '', env: '' }) {
       if (!options.namespace) options.namespace = 'default';
       // kubectl get deploy,sts,svc,configmap,secret -n default -o yaml --export > default.yaml
       const hostTest = options?.hostTest
@@ -683,6 +701,18 @@ spec:
         silentOnError: true,
       });
       if (!info) return null;
+      // Env-scoped resolution: read THIS deploy's colour from its own service
+      // name (`<deployId>-<env>-<colour>-service`). Essential for shared
+      // multi-instance hosts, where one HTTPProxy holds several variants' routes
+      // on possibly different colours — a whole-document `.match('blue')` would
+      // return whichever colour appears first, i.e. a sibling's, not this one's.
+      // The regex is anchored on the full `<deployId>-<env>-` prefix so
+      // `dd-cyberia-mmo-server` never matches `dd-cyberia-mmo-server-forest`.
+      if (options.env) {
+        const escaped = deployId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const match = info.match(new RegExp(`${escaped}-${options.env}-(blue|green)-service`));
+        return match ? match[1] : null;
+      }
       return info.match('blue') ? 'blue' : info.match('green') ? 'green' : null;
     },
 
@@ -825,9 +855,9 @@ EOF`);
           const deployId = _deployId.trim();
           const instances = [];
           if (fs.existsSync(`./engine-private/conf/${deployId}/conf.instances.json`)) {
-            const confInstances = JSON.parse(
-              fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
-            );
+            // Expands multiInstance variants so status lists every deployed
+            // instance (mmo-server, mmo-server-forest, …), not just the templates.
+            const confInstances = loadConfInstances(deployId);
             for (const instance of confInstances) {
               const _deployId = `${deployId}-${instance.id}`;
               instances.push({
@@ -838,7 +868,7 @@ EOF`);
                 toPort: instance.toPort,
                 fromDebugPort: instance.fromDebugPort,
                 toDebugPort: instance.toDebugPort,
-                traffic: Underpost.deploy.getCurrentTraffic(_deployId, { namespace, hostTest: instance.host }),
+                traffic: Underpost.deploy.getCurrentTraffic(_deployId, { namespace, hostTest: instance.host, env }),
               });
             }
           }
@@ -1075,7 +1105,13 @@ EOF`);
      *      runners derive it from the comma-path field or `--node-name`
      *      (`run sync`: `path.split(',')[4]` > `--node-name` > default) and from
      *      `--node-name` directly (`run instance`).
-     *   2. **Cluster-type default** — when no explicit node is given: `kind-worker`
+     *   2. **`UNDERPOST_DEPLOY_NODE` env** — for kubeadm / k3s, the configured
+     *      target node name. This makes hostPath PV `nodeAffinity` deterministic
+     *      regardless of where the manifest is *built*: building inside a
+     *      container or CI runner would otherwise leak that box's `os.hostname()`
+     *      (e.g. a random container id) into `nodeSelector`, pinning the PV to a
+     *      node that does not exist in the cluster.
+     *   3. **Cluster-type default** — when nothing above is set: `kind-worker`
      *      for a kind cluster (the node that hosts kind hostPath volumes),
      *      otherwise the control-plane / current host (`os.hostname()`) for
      *      kubeadm / k3s. With no explicit cluster flag, `development` is treated
@@ -1093,7 +1129,8 @@ EOF`);
     resolveDeployNode({ node = '', kind = false, kubeadm = false, k3s = false, env = '' } = {}) {
       if (node) return node;
       const isKind = kind || (!kubeadm && !k3s && env !== 'production');
-      return isKind ? 'kind-worker' : os.hostname();
+      if (isKind) return 'kind-worker';
+      return process.env.UNDERPOST_DEPLOY_NODE || os.hostname();
     },
 
     /**
@@ -1241,13 +1278,18 @@ EOF
           volumeName = `${volumeName}-${version}`;
           claimName = claimName ? `${claimName}-${version}` : null;
         }
+        // The pod-local volume name is a DNS-1123 label (max 63 chars); the PVC
+        // `claimName` it references is a subdomain (max 253) and stays verbatim.
+        // Per-variant instance names append <deployId>-<env>-<traffic> and can
+        // exceed 63, so clamp only the pod-local name (mount name must match it).
+        const podVolumeName = k8sVolumeName(volumeName);
         _volumeMounts += `
-        - name: ${volumeName}
+        - name: ${podVolumeName}
           mountPath: ${volumeMountPath}
 ${secret ? `          readOnly: true\n` : ''}`;
 
         _volumes += `
-    - name: ${volumeName}
+    - name: ${podVolumeName}
  ${
    emptyDir
      ? `     emptyDir: {}`

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);
@@ -191,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.70
+APP_TAG=v3.2.80
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest
@@ -361,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
@@ -371,17 +516,25 @@ datasources:
    * @memberof UnderpostDockerCompose
    */
   static generate(options = {}) {
-    // Custom workflow: docker-compose.yml, compose.env, and nginx.conf are
-    // pre-authored in the canonical dir and used as-is — do NOT generate them.
-    // Only (re)write the required MongoDB entrypoint (replica-set bootstrap),
-    // the single generated infra artifact, into <canonical>/mongodb so the
-    // stack stays self-contained under `--project-directory`.
+    // 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;
     }
 
@@ -491,9 +644,10 @@ datasources:
       silentOnError: true,
     });
 
-    // Custom workflow: the compose file, compose.env, and nginx.conf are
-    // hand-authored source — never prune them. Only drop the one generated
-    // artifact (the mongo entrypoint), regenerated on the next --up/--generate.
+    // 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`);

package/src/cli/fs.js

@@ -315,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

@@ -117,20 +117,38 @@ class UnderpostImage {
       };
       // 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);
+      // 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 GitHub credentials as build secrets', { ids: secretFlags.length });
+      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)
         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`,
+            } -t ${imageName} --pull=never --cap-add=CAP_AUDIT_WRITE${cache}${secretArgs}${buildArgStr} --network host`,
           );
         } finally {
           for (const file of secretTmpFiles) {

package/src/cli/index.js

@@ -108,6 +108,10 @@ program
   .option('--edit', 'Edit last commit.')
   .option('--deploy-id <deploy-id>', 'Sets the deployment configuration ID for the commit context.')
   .option('--cached', 'Commit staged changes only or context.')
+  .option(
+    '--init-repo [origin]',
+    'Initialize a git repository at the specified path. Optionally set the git remote origin URL.',
+  )
   .option('--hashes <hashes>', 'Comma-separated list of specific file hashes of commits.')
   .option('--extension <extension>', 'specific file extensions of commits.')
   .option('--changelog', 'Print the plain changelog of the last N commits (see --from-n-commit, default 1).')
@@ -758,6 +762,7 @@ program
     '--test',
     'Enables test/generic-purpose mode for the runner (e.g. use self-signed TLS instead of cert-manager).',
   )
+  .option('--branch <branch>', 'Sets the branch for git operations (default: current branch).')
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 

package/src/cli/release.js

@@ -135,6 +135,10 @@ const buildVersionBumpTargets = () => [
     file: 'src/runtime/engine-cyberia/docker-compose.yml',
     patterns: /(_TAG:-v)\d+\.\d+\.\d+/g,
   },
+  {
+    file: 'engine-private/conf/dd-cyberia/docker-compose/cyberia/docker-compose.yml',
+    patterns: /(_TAG:-v)\d+\.\d+\.\d+/g,
+  },
 
   // ── Cyberia CLI dev image tar/name defaults (bin/cyberia.js). ──
   {

package/src/cli/repository.js

@@ -21,6 +21,7 @@ import {
   getDataDeploy,
   buildReplicaId,
   writeEnv,
+  readConfInstances,
 } from '../server/conf.js';
 import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../client-builder/client-build.js';
 import { DefaultConf } from '../../conf.js';
@@ -145,6 +146,14 @@ class UnderpostRepository {
     ) {
       if (!repoPath) repoPath = '.';
 
+      if (options.initRepo) {
+        Underpost.repo.initLocalRepo({
+          path: repoPath,
+          origin: typeof options.initRepo === 'string' ? options.initRepo : undefined,
+        });
+        return;
+      }
+
       if (options.hasChanges) {
         const status = shellExec(`cd ${repoPath} && git status --porcelain`, {
           stdout: true,
@@ -1854,8 +1863,10 @@ Prevent build private config repo.`,
         const confPath = `./engine-private/conf/${deployId}/conf.instances.json`;
         if (!fs.existsSync(confPath)) continue;
         try {
-          const instances = JSON.parse(fs.readFileSync(confPath, 'utf8'));
-          const match = instances.find((i) => i && i.runtime === runtime);
+          // readConfInstances returns the bare array of entries. The template
+          // entries carry runtime + metadata.repository, so the un-expanded list
+          // is enough here (no need to expand variants).
+          const match = readConfInstances(deployId).find((i) => i && i.runtime === runtime);
           if (match && match.metadata && match.metadata.repository) {
             logger.info(`[resolveInstanceRepo] resolved from ${confPath}`, {
               runtime,