underpost 3.2.30 → 3.2.70

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.')
@@ -434,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 });
   });
@@ -692,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.')
@@ -765,6 +774,12 @@ program
     '--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).')

package/src/cli/release.js

@@ -117,9 +117,53 @@ const buildVersionBumpTargets = () => [
       /(underpost-engine:v)\d+\.\d+\.\d+/g,
       /(type=raw,value=v)\d+\.\d+\.\d+/g,
       /(UNDERPOST_VERSION=)\d+\.\d+\.\d+/g,
+      /(UNDERPOST_VERSION:\s*['"]?)\d+\.\d+\.\d+/g,
     ],
   },
 
+  // ── Docker-compose image-tag defaults. Root compose + generator + cyberia runtime compose.
+  //    Tags live in `${VAR:-vX.Y.Z}` / `VAR=vX.Y.Z` shapes bumpp cannot detect. ──
+  {
+    file: 'docker-compose.yml',
+    patterns: /(_TAG:-v)\d+\.\d+\.\d+/g,
+  },
+  {
+    file: 'src/cli/docker-compose.js',
+    patterns: /(_TAG=v)\d+\.\d+\.\d+/g,
+  },
+  {
+    file: 'src/runtime/engine-cyberia/docker-compose.yml',
+    patterns: /(_TAG:-v)\d+\.\d+\.\d+/g,
+  },
+
+  // ── Cyberia CLI dev image tar/name defaults (bin/cyberia.js). ──
+  {
+    file: 'bin/cyberia.js',
+    patterns: [/(-dev_v)\d+\.\d+\.\d+(?=\.tar)/g, /(-dev:v)\d+\.\d+\.\d+/g],
+  },
+
+  // ── Runtime Dockerfiles: `ARG UNDERPOST_VERSION=X.Y.Z` build-arg defaults. ──
+  {
+    dir: 'src/runtime',
+    match: /^Dockerfile(\.\w+)?$/,
+    patterns: /(ARG UNDERPOST_VERSION=)\d+\.\d+\.\d+/g,
+    recursive: true,
+  },
+
+  // ── Runtime compose.env shipped tag defaults ──
+  {
+    dir: 'src/runtime',
+    match: /^compose\.env$/,
+    patterns: /(_TAG=v)\d+\.\d+\.\d+/g,
+    recursive: true,
+  },
+
+  // ── Deploy-monitor smoke-test image default (scripts/test-monitor.sh). ──
+  {
+    file: 'scripts/test-monitor.sh',
+    patterns: /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+  },
+
   // ── engine-private confs (gitignored — bumped only if present). ──
   {
     dir: 'engine-private/conf',
@@ -448,11 +492,10 @@ class UnderpostRelease {
       let commitMsg = message;
       if (!commitMsg) {
         shellCd('/home/dd/engine');
-        const rawMsg = shellExec(`node bin cmt --changelog 1 --changelog-no-hash`, {
+        commitMsg = shellExec(`node bin cmt --changelog-msg --changelog-no-hash`, {
           stdout: true,
           silent: true,
         }).trim();
-        commitMsg = Underpost.repo.sanitizeChangelogMessage(rawMsg);
         shellCd('/home/dd');
       }
       commitMsg = (commitMsg || '').trim() || `Update ${repoName} repository`;
@@ -492,11 +535,10 @@ class UnderpostRelease {
       let commitMsg = message;
       if (!commitMsg) {
         shellCd('/home/dd/engine');
-        const rawMsg = shellExec(`node bin cmt --changelog 1 --changelog-no-hash`, {
+        commitMsg = shellExec(`node bin cmt --changelog-msg --changelog-no-hash`, {
           stdout: true,
           silent: true,
         }).trim();
-        commitMsg = Underpost.repo.sanitizeChangelogMessage(rawMsg);
       }
       commitMsg = (commitMsg || '').trim() || `Update pwa-microservices-template repository`;
       shellCd('/home/dd');

package/src/cli/repository.js

@@ -218,7 +218,7 @@ class UnderpostRepository {
         return;
       }
 
-      if (options.changelog !== undefined || options.changelogBuild) {
+      if (options.changelog !== undefined || options.changelogBuild || options.changelogMsg !== undefined) {
         const releaseMatch = 'New release v:';
         // Helper: parse [<tag>] commits into grouped sections
         const buildSectionChangelog = (commits) => {
@@ -255,7 +255,8 @@ class UnderpostRepository {
             stdout: true,
             silent: true,
             disableLog: true,
-          });
+            silentOnError: true,
+          }).toString();
           return rawLog
             .split('\n')
             .map((line) => {
@@ -346,15 +347,18 @@ class UnderpostRepository {
           fs.writeFileSync(changelogPath, `# Changelog\n\n${changelog}`);
           logger.info('CHANGELOG.md built at', changelogPath);
         } else {
-          // --changelog [latest-n]: print changelog of last N commits (default: 1)
-          const hasExplicitCount =
-            options.changelog !== undefined && options.changelog !== true && !isNaN(parseInt(options.changelog));
-          const scanLimit = hasExplicitCount ? parseInt(options.changelog) : 1;
-          const allCommits = fetchHistory(scanLimit);
-
-          const sections = buildVersionSections(allCommits);
-          let changelog = renderSections(sections);
-          console.log(changelog || `No changelog entries found.\n`);
+          // --changelog / --changelog-msg: message from the last N commits, where N is --from-n-commit
+          // (default 1, last commit only). No auto-detection.
+          const n = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+          const sections = buildVersionSections(fetchHistory(n));
+          const changelog = renderSections(sections);
+          if (options.changelogMsg !== undefined) {
+            // Sanitized, commit-ready message; empty string when there are no tagged entries so
+            // callers fall back to their own generic default instead of a placeholder.
+            console.log(Underpost.repo.sanitizeChangelogMessage(changelog));
+          } else {
+            console.log(changelog || `No changelog entries found.\n`);
+          }
         }
 
         return;
@@ -1257,17 +1261,40 @@ Prevent build private config repo.`,
       return copiedFiles;
     },
 
+    /**
+     * Resolves the default branch for a remote GitHub repository by querying
+     * `git ls-remote --symref` and extracting the HEAD ref target.
+     * Falls back to `main` when detection fails.
+     * @param {string} repo - The GitHub repository (e.g., "owner/repo").
+     * @returns {string} The default branch name (e.g. "main" or "master").
+     * @memberof UnderpostRepository
+     */
+    getDefaultBranch(repo) {
+      if (!repo) return 'main';
+      const authUrl = Underpost.repo.resolveAuthUrl(repo);
+      const raw = shellExec(
+        `GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote --symref "${authUrl}" HEAD 2>&1`,
+        { stdout: true, silent: true, disableLog: true, silentOnError: true },
+      );
+      // --symref emits a line like: ref: refs/heads/main	HEAD
+      const match = typeof raw === 'string' ? raw.match(/^ref:\s*refs\/heads\/(\S+)\tHEAD$/m) : null;
+      const branch = match ? match[1] : 'main';
+      logger.info('getDefaultBranch', { repo, branch });
+      return branch;
+    },
+
     /**
      * Dispatches a GitHub Actions workflow using gh CLI or curl fallback.
      * @param {object} options - Dispatch options.
      * @param {string} options.repo - The GitHub repository (e.g., "owner/repo").
      * @param {string} options.workflowFile - The workflow file name (e.g., "engine-core.cd.yml").
-     * @param {string} [options.ref='master'] - The git ref to dispatch against.
+     * @param {string} [options.ref] - The git ref to dispatch against. Auto-detects the remote's default branch when omitted.
      * @param {object} [options.inputs={}] - Key-value inputs for the workflow_dispatch event.
      * @memberof UnderpostRepository
      */
-    dispatchWorkflow(options = { repo: '', workflowFile: '', ref: 'master', inputs: {} }) {
-      const { repo, workflowFile, ref, inputs } = options;
+    dispatchWorkflow(options = { repo: '', workflowFile: '', ref: '', inputs: {} }) {
+      const { repo, workflowFile, inputs } = options;
+      const ref = options.ref || Underpost.repo.getDefaultBranch(repo);
       const ghAvailable = shellExec('command -v gh 2>/dev/null', {
         stdout: true,
         silent: true,
@@ -1344,14 +1371,18 @@ Prevent build private config repo.`,
       if (!url) return false;
       const authUrl = Underpost.repo.resolveAuthUrl(url);
       // GIT_TERMINAL_PROMPT=0 prevents git from hanging on credential prompts inside containers.
-      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git ls-remote "${authUrl}" HEAD 2>&1`, {
+      // `-c credential.helper=` disables any host-configured credential helper so its stderr
+      // warnings don't pollute the ls-remote output; the token is already embedded in authUrl.
+      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote "${authUrl}" HEAD 2>&1`, {
         stdout: true,
         silent: true,
         disableLog: true,
         silentOnError: true,
       });
-      logger.info('isRemoteRepo', { url, raw: (raw || '').slice(0, 120) });
-      return typeof raw === 'string' && /^[0-9a-f]{40}\t/m.test(raw);
+      const refLine = typeof raw === 'string' ? (raw.match(/^[0-9a-f]{40}\t.*$/m) || [])[0] : undefined;
+      const accessible = !!refLine;
+      logger.info('isRemoteRepo', { url, accessible, ref: refLine || (raw || '').trim().split('\n').pop() });
+      return accessible;
     },
 
     /**
@@ -1422,17 +1453,31 @@ Prevent build private config repo.`,
      * @memberof UnderpostRepository
      */
     getUnpushedCount(repoPath = '.', fallback = 1) {
+      // Every git call is silentOnError: a detached HEAD (CI checkout) or a missing upstream must
+      // degrade to the fallback, never throw — otherwise the thrown error is logged to stdout and
+      // can be captured as a commit message by callers that read this command's output.
       const branch = shellExec(`cd ${repoPath} && git branch --show-current`, {
         stdout: true,
         silent: true,
         disableLog: true,
-      }).trim();
-      shellExec(`cd ${repoPath} && git fetch origin 2>/dev/null`, { silent: true, disableLog: true });
+        silentOnError: true,
+      })
+        .toString()
+        .trim();
+      if (!branch) return { count: fallback, branch: '', hasUnpushed: false };
+      shellExec(`cd ${repoPath} && git fetch origin 2>/dev/null`, {
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      });
       const raw = shellExec(`cd ${repoPath} && git rev-list --count origin/${branch}..HEAD 2>/dev/null`, {
         stdout: true,
         silent: true,
         disableLog: true,
-      }).trim();
+        silentOnError: true,
+      })
+        .toString()
+        .trim();
       const count = parseInt(raw);
       const hasUnpushed = !isNaN(count) && count > 0;
       return { count: hasUnpushed ? count : fallback, branch, hasUnpushed };
@@ -1447,7 +1492,7 @@ Prevent build private config repo.`,
      */
     sanitizeChangelogMessage(message) {
       if (!message) return '';
-      return message
+      const sanitized = message
         .replace(/^##\s+\d{4}-\d{2}-\d{2}\s*/gm, '')
         .replace(/^###\s+(\S+)\s*/gm, '[$1] ')
         .replace(/^- /gm, '')
@@ -1459,6 +1504,9 @@ Prevent build private config repo.`,
         .join('\n')
         .trim()
         .replaceAll('] - ', '] ');
+      // The empty-changelog placeholder must never become a commit message; return empty so
+      // callers fall back to their own generic default.
+      return sanitized === 'No changelog entries found.' ? '' : sanitized;
     },
     /**
      * Initializes a git repository at the given path and configures user identity
@@ -1783,12 +1831,17 @@ Prevent build private config repo.`,
      *  4. Falls back to `${GITHUB_USERNAME}/engine` when no match is found.
      *
      * @param {string} [runtime=''] - The runtime identifier to look up (e.g. `'cyberia-server'`, `'cyberia-client'`).
+     * @param {boolean} [ownRuntimeRepo=false] - Whether to check for the runtime's own repository.
      * @returns {string} The resolved `owner/repo` string.
      * @memberof UnderpostRepository
      */
-    resolveInstanceRepo(runtime = '') {
+    resolveInstanceRepo(runtime = '', ownRuntimeRepo = false) {
       const fallback = `${process.env.GITHUB_USERNAME}/engine`;
       if (!runtime) return fallback;
+      // A `.dev` suffix selects the development image workflow
+      // (docker-image.<runtime>.dev.ci.yml) but resolves to the same instance
+      // repo as its production counterpart, so strip it before matching.
+      runtime = runtime.replace(/\.dev$/, '');
       const ddRouter = './engine-private/deploy/dd.router';
       const deployIds = fs.existsSync(ddRouter)
         ? fs
@@ -1814,6 +1867,16 @@ Prevent build private config repo.`,
           logger.warn(`[resolveInstanceRepo] failed to parse ${confPath}: ${err.message}`);
         }
       }
+      if (ownRuntimeRepo) {
+        const runtimeRepo = Underpost.repo.isRemoteRepo(`${process.env.GITHUB_USERNAME}/${runtime}`);
+        if (runtimeRepo) {
+          logger.info(`[resolveInstanceRepo] resolved from ${process.env.GITHUB_USERNAME}/${runtime}`, {
+            runtime,
+            repo: `${process.env.GITHUB_USERNAME}/${runtime}`,
+          });
+          return `${process.env.GITHUB_USERNAME}/${runtime}`;
+        }
+      }
       return fallback;
     },