underpost 3.2.8 → 3.2.10

package/src/cli/release.js

@@ -10,6 +10,7 @@
  */
 
 import fs from 'fs-extra';
+import path from 'path';
 import dotenv from 'dotenv';
 import { pbcopy, shellCd, shellExec } from '../server/process.js';
 import { loggerFactory } from '../server/logger.js';
@@ -18,6 +19,222 @@ import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);
 
+/**
+ * Files that must never be touched by a version bump, even if they happen to contain a
+ * literal version string. CHANGELOG is historical; logs/ and node_modules/ are runtime
+ * outputs; engine-private/.env.* and secrets must not be rewritten by regex.
+ */
+const VERSION_BUMP_SKIP = [
+  /(^|\/)CHANGELOG\.md$/i,
+  /(^|\/)logs\//,
+  /(^|\/)node_modules\//,
+  /(^|\/)\.git\//,
+  /(^|\/)engine-private\/.*\.env(\..*)?$/,
+];
+
+const isSkipped = (filePath) => VERSION_BUMP_SKIP.some((re) => re.test(filePath));
+
+/**
+ * Declarative regex-based version bump targets for files bumpp cannot handle natively
+ * (image tags, doc strings, README badges, build-args, etc.).
+ *
+ * Each target is one of:
+ *   - { file: 'path/to/file', patterns: RegExp | RegExp[] }
+ *   - { dir: 'dir', match: RegExp, patterns: RegExp | RegExp[], recursive?: boolean }
+ *
+ * Every pattern MUST have exactly one capture group: the prefix to preserve. The replacement
+ * is `$1<newVersion>`. Use a lookahead `(?=...)` to anchor a trailing context (closing quote,
+ * backtick, etc.) without consuming it. This keeps the callback signature trivial.
+ *
+ * The walker iterates targets, applies patterns to each matching file, and reports the
+ * number of substitutions per file. Files that match nothing are silently skipped.
+ */
+const buildVersionBumpTargets = () => [
+  // ── src/index.js — anchored to the static class field, never a bare replaceAll. ──
+  {
+    file: 'src/index.js',
+    patterns: /(static version = ['"]v)\d+\.\d+\.\d+(?=['"])/g,
+  },
+
+  // ── README + CLI-HELP fallbacks. CLI-HELP is regenerated by `deploy cli-docs`, but bump
+  //    it too so the file is consistent if the regeneration step is skipped. ──
+  {
+    file: 'README.md',
+    patterns: [
+      /(socket\.dev\/api\/badge\/npm\/package\/underpost\/)\d+\.\d+\.\d+/g,
+      /(socket\.dev\/npm\/package\/underpost\/overview\/)\d+\.\d+\.\d+/g,
+      /(ci\/cd cli v)\d+\.\d+\.\d+/gi,
+    ],
+  },
+  {
+    file: 'CLI-HELP.md',
+    patterns: /(ci\/cd cli v)\d+\.\d+\.\d+/gi,
+    optional: true,
+  },
+
+  // ── Cyberia + nexodev docs. ──
+  {
+    dir: 'src/client/public/cyberia-docs',
+    match: /\.md$/,
+    patterns: [
+      /(\*\*(?:Current )?[Vv]ersion:\*\* )\d+\.\d+\.\d+/g,
+      /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+    ],
+    recursive: true,
+  },
+  {
+    dir: 'src/client/public/nexodev/docs/references',
+    match: /\.md$/,
+    patterns: [
+      /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+      /(UNDERPOST_VERSION=)\d+\.\d+\.\d+/g,
+      /(ci\/cd cli v)\d+\.\d+\.\d+/gi,
+      // version tag bumps inside markdown narrative, e.g. `v3.2.9`, `v3.2.10`, …
+      /(`v)\d+\.\d+\.\d+(?=`)/g,
+    ],
+    recursive: true,
+  },
+
+  // ── Kubernetes manifests. Covers deployment.yaml + cronjob yamls under dd-cron. ──
+  {
+    dir: 'manifests/deployment',
+    match: /deployment\.yaml$/,
+    patterns: [
+      /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+      /(engine\.version: )\d+\.\d+\.\d+/g,
+    ],
+    recursive: true,
+  },
+  {
+    dir: 'manifests/cronjobs',
+    match: /\.yaml$/,
+    patterns: /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+    recursive: true,
+  },
+
+  // ── GitHub Actions workflows. Single sweep across docker-image.*.ci.yml, engine-*.cd.yml,
+  //    and the root docker-image.ci.yml — replaces previous three separate loops. ──
+  {
+    dir: '.github/workflows',
+    match: /\.(yml|yaml)$/,
+    patterns: [
+      /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+      /(underpost-engine:v)\d+\.\d+\.\d+/g,
+      /(type=raw,value=v)\d+\.\d+\.\d+/g,
+      /(UNDERPOST_VERSION=)\d+\.\d+\.\d+/g,
+    ],
+  },
+
+  // ── engine-private confs (gitignored — bumped only if present). ──
+  {
+    dir: 'engine-private/conf',
+    match: /(?:deployment\.yaml|conf\.instances\.json)$/,
+    patterns: [
+      /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+      /(underpost-engine:v)\d+\.\d+\.\d+/g,
+      /(engine\.version: )\d+\.\d+\.\d+/g,
+      /(v)\d+\.\d+\.\d+/g,
+    ],
+    recursive: true,
+    optional: true,
+  },
+];
+
+/**
+ * Walks a directory (optionally recursively) and returns paths matching `match`.
+ */
+const walkDir = (dir, match, recursive) => {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(cur, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of entries) {
+      const full = path.join(cur, ent.name);
+      if (ent.isDirectory()) {
+        if (recursive) stack.push(full);
+      } else if (ent.isFile() && match.test(ent.name) && !isSkipped(full)) {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+};
+
+/**
+ * Applies an array of regex patterns to a single file in place. Substitutes only when the
+ * matched version literally equals `oldVersion` — narrative references to other versions
+ * (e.g. example tags `(v3.2.9, v3.2.10, …)`) are left untouched.
+ *
+ * Returns the substitution count (0 if nothing matched).
+ */
+const bumpFile = (filePath, patterns, oldVersion, newVersion, { dryRun }) => {
+  if (isSkipped(filePath)) return 0;
+  if (!fs.existsSync(filePath)) return 0;
+  const original = fs.readFileSync(filePath, 'utf8');
+  const regexes = Array.isArray(patterns) ? patterns : [patterns];
+  let updated = original;
+  let count = 0;
+  for (const re of regexes) {
+    updated = updated.replace(re, (m, prefix) => {
+      const matchedVersion = m.match(/\d+\.\d+\.\d+/)?.[0];
+      if (matchedVersion !== oldVersion) return m;
+      count += 1;
+      return `${prefix}${newVersion}`;
+    });
+  }
+  if (count > 0 && updated !== original && !dryRun) {
+    fs.writeFileSync(filePath, updated, 'utf8');
+  }
+  return count;
+};
+
+/**
+ * Bumps every non-canonical file declared in VERSION_BUMP_TARGETS.
+ * Returns a per-file report so callers can print a summary.
+ *
+ * @param {string} oldVersion - The version currently in the files (pre-bump).
+ * @param {string} newVersion - The version to write.
+ * @param {{dryRun?: boolean}} [opts]
+ * @returns {Array<{file: string, count: number}>}
+ */
+const bumpAuxiliaryFiles = (oldVersion, newVersion, { dryRun = false } = {}) => {
+  const report = [];
+  if (oldVersion === newVersion) return report;
+  for (const target of buildVersionBumpTargets()) {
+    const files = target.file ? [target.file] : walkDir(target.dir, target.match, target.recursive ?? false);
+    for (const file of files) {
+      if (target.optional && !fs.existsSync(file)) continue;
+      const count = bumpFile(file, target.patterns, oldVersion, newVersion, { dryRun });
+      if (count > 0) report.push({ file, count });
+    }
+  }
+  return report;
+};
+
+/**
+ * Prints a per-file change summary table.
+ */
+const printBumpReport = (report, { dryRun }) => {
+  const header = dryRun ? 'Version bump (dry-run) — would change:' : 'Version bump — files updated:';
+  logger.info(header);
+  if (!report.length) {
+    console.log('  (no files matched)');
+    return;
+  }
+  const maxLen = Math.max(...report.map((r) => r.file.length));
+  for (const { file, count } of report) {
+    console.log(`  ${file.padEnd(maxLen + 2)} ${count} match${count === 1 ? '' : 'es'}`);
+  }
+  console.log(`  Total: ${report.length} file(s), ${report.reduce((s, r) => s + r.count, 0)} substitution(s)`);
+};
+
 /**
  * Kills any Node.js dev-server or nodemon processes that may hold file locks
  * (e.g. overwriting package.json). Skips VSCode internals and the current process.
@@ -46,154 +263,94 @@ class UnderpostRelease {
      * Builds a new version of the Underpost engine.
      *
      * Performs the full version build pipeline:
-     * 1. Loads production environment and pulls latest code.
-     * 2. Kills running dev servers on ports 4001-4003.
-     * 3. Builds and tests the pwa-microservices-template.
-     * 4. Bumps version in package.json, package-lock.json, and all conf package files.
-     * 5. Updates deployment YAML manifests and Docker image CI workflow with new version.
-     * 6. Updates src/index.js version string.
-     * 7. Rebuilds CLI docs, dependencies, client builds, deploy manifests, and default confs.
-     * 8. Syncs cron setup-start scripts and builds changelog.
+     * 1. Loads production env and pulls latest code; kills dev servers on ports 4001-4003.
+     * 2. Builds and smoke-tests the pwa-microservices-template (aborts on error).
+     * 3. Canonical version files: delegates to `bumpp` (driven by `bump.config.js`). Bumps
+     *    package.json, package-lock.json (root + packages['']), and every
+     *    engine-private/conf/**\/package.json.
+     * 4. Auxiliary files: anchored-regex walker over VERSION_BUMP_TARGETS — covers
+     *    src/index.js, README, cyberia-docs, nexodev docs, manifests (deployment + cronjobs),
+     *    .github/workflows (image tags, type=raw, UNDERPOST_VERSION build-args), and
+     *    engine-private confs (deployment.yaml + conf.instances.json). Files in
+     *    VERSION_BUMP_SKIP (CHANGELOG, logs/, .env.*, node_modules/) are never touched.
+     *    The walker only rewrites occurrences whose version literally equals the pre-bump
+     *    version — narrative references like `(v3.2.9, v3.2.10, …)` are preserved.
+     * 5. Rebuilds CLI docs, deps, client bundle, deploy manifests, default confs.
+     * 6. Syncs cron setup-start scripts and builds the changelog.
+     *
+     * With `options.dryRun: true`, steps 3–4 print a per-file substitution report and exit
+     * without writing files or running steps 5–6.
      *
      * @method build
      * @param {string} [newVersion] - The new version string to set. Defaults to current version if not provided.
-     * @param {object} [options] - Commander options object (unused, reserved for future flags).
+     * @param {{dryRun?: boolean}} [options] - Commander options. `--dry-run` previews changes.
      * @memberof UnderpostRelease
      */
-    async build(newVersion, options) {
+    async build(newVersion, options = {}) {
+      const dryRun = !!options.dryRun;
       dotenv.config({ path: `./engine-private/conf/dd-cron/.env.production`, override: true });
       shellCd(`/home/dd/engine`);
-      killDevServers();
-      Underpost.repo.clean({ paths: ['/home/dd/engine', '/home/dd/engine/engine-private '] });
-      shellExec(`node bin pull . ${process.env.GITHUB_USERNAME}/engine`);
-      shellExec(`npm run update:template`);
-      shellExec(`cd ../pwa-microservices-template && npm install && npm run build`);
-      console.log(fs.existsSync(`../pwa-microservices-template/engine-private/conf/dd-default`));
-      shellExec(`cd ../pwa-microservices-template && ENABLE_FILE_LOGS=true timeout 5s npm run dev`, {
-        async: true,
-      });
-      await timer(5500);
-      const templateRunnerResult = fs.readFileSync(`../pwa-microservices-template/logs/start.js/all.log`, 'utf8');
-      logger.info('Test template runner result');
-      console.log(templateRunnerResult);
-      if (!templateRunnerResult || templateRunnerResult.toLowerCase().match('error')) {
-        logger.error('Test template runner result failed');
-        return;
-      }
-      killDevServers();
-      shellCd(`/home/dd/engine`);
-      Underpost.repo.clean({ paths: ['/home/dd/engine', '/home/dd/engine/engine-private '] });
+
+      // ── Resolve from/to versions up front. Used by every bump step + downstream commands. ──
       const originPackageJson = JSON.parse(fs.readFileSync(`package.json`, 'utf8'));
-      if (!newVersion) newVersion = originPackageJson.version;
       const { version } = originPackageJson;
-      originPackageJson.version = newVersion;
-      fs.writeFileSync(`package.json`, JSON.stringify(originPackageJson, null, 4), 'utf8');
-
-      const originPackageLockJson = JSON.parse(fs.readFileSync(`package-lock.json`, 'utf8'));
-      originPackageLockJson.version = newVersion;
-      originPackageLockJson.packages[''].version = newVersion;
-      fs.writeFileSync(`package-lock.json`, JSON.stringify(originPackageLockJson, null, 4), 'utf8');
+      if (!newVersion) newVersion = version;
+      logger.info(`Release build — bumping ${version} → ${newVersion}${dryRun ? ' (dry-run)' : ''}`);
 
-      if (fs.existsSync(`./engine-private/conf`)) {
-        const files = await fs.readdir(`./engine-private/conf`, { recursive: true });
-        for (const relativePath of files) {
-          const filePah = `./engine-private/conf/${relativePath.replaceAll(`\\`, '/')}`;
-          if (filePah.split('/').pop() === 'package.json') {
-            const originPackage = JSON.parse(fs.readFileSync(filePah, 'utf8'));
-            originPackage.version = newVersion;
-            fs.writeFileSync(filePah, JSON.stringify(originPackage, null, 4), 'utf8');
-          }
-          if (filePah.split('/').pop() === 'deployment.yaml') {
-            fs.writeFileSync(
-              filePah,
-              fs
-                .readFileSync(filePah, 'utf8')
-                .replaceAll(`v${version}`, `v${newVersion}`)
-                .replaceAll(`engine.version: ${version}`, `engine.version: ${newVersion}`),
-              'utf8',
-            );
-          }
+      if (!dryRun) {
+        killDevServers();
+        Underpost.repo.clean({ paths: ['/home/dd/engine', '/home/dd/engine/engine-private '] });
+        shellExec(`node bin pull . ${process.env.GITHUB_USERNAME}/engine`);
+        shellExec(`npm run update:template`);
+        shellExec(`cd ../pwa-microservices-template && npm install && npm run build`);
+        console.log(fs.existsSync(`../pwa-microservices-template/engine-private/conf/dd-default`));
+        shellExec(`cd ../pwa-microservices-template && ENABLE_FILE_LOGS=true timeout 5s npm run dev`, {
+          async: true,
+        });
+        await timer(5500);
+        const templateRunnerResult = fs.readFileSync(`../pwa-microservices-template/logs/start.js/all.log`, 'utf8');
+        logger.info('Test template runner result');
+        console.log(templateRunnerResult);
+        if (!templateRunnerResult || templateRunnerResult.toLowerCase().match('error')) {
+          logger.error('Test template runner result failed');
+          return;
         }
+        killDevServers();
+        shellCd(`/home/dd/engine`);
+        Underpost.repo.clean({ paths: ['/home/dd/engine', '/home/dd/engine/engine-private '] });
       }
 
-      fs.writeFileSync(
-        `./manifests/deployment/dd-default-development/deployment.yaml`,
-        fs
-          .readFileSync(`./manifests/deployment/dd-default-development/deployment.yaml`, 'utf8')
-          .replaceAll(`underpost-engine:v${version}`, `underpost-engine:v${newVersion}`),
-        'utf8',
-      );
-
-      if (fs.existsSync(`./.github/workflows/docker-image.ci.yml`))
-        fs.writeFileSync(
-          `./.github/workflows/docker-image.ci.yml`,
-          fs
-            .readFileSync(`./.github/workflows/docker-image.ci.yml`, 'utf8')
-            .replaceAll(`underpost-engine:v${version}`, `underpost-engine:v${newVersion}`),
-          'utf8',
-        );
-
-      // Update underpost/* image versions in all engine-*.cd.yml workflows.
-      for (const wf of fs.readdirSync(`./.github/workflows`)) {
-        if (!wf.match(/^engine-.+\.cd\.yml$/)) continue;
-        const wfPath = `./.github/workflows/${wf}`;
-        const updated = fs
-          .readFileSync(wfPath, 'utf8')
-          .replace(/underpost\/([^:'"]+):v[0-9]+\.[0-9]+\.[0-9]+/g, `underpost/$1:v${newVersion}`);
-        fs.writeFileSync(wfPath, updated, 'utf8');
-      }
-
-      // Update version tag in all runtime docker image workflows (type=raw,value=v<version>).
-      for (const wf of fs.readdirSync(`./.github/workflows`)) {
-        if (!wf.match(/^docker-image\..+\.ci\.yml$/) || wf === 'docker-image.ci.yml') continue;
-        const wfPath = `./.github/workflows/${wf}`;
-        fs.writeFileSync(
-          wfPath,
-          fs.readFileSync(wfPath, 'utf8').replaceAll(`type=raw,value=v${version}`, `type=raw,value=v${newVersion}`),
-          'utf8',
-        );
-      }
-
-      // Update image version in all conf.instances.json files for underpost/* images.
-      if (fs.existsSync(`./engine-private/conf`)) {
-        const confFiles = await fs.readdir(`./engine-private/conf`, { recursive: true });
-        for (const relativePath of confFiles) {
-          const filePath = `./engine-private/conf/${relativePath.replaceAll('\\', '/')}`;
-          if (filePath.split('/').pop() !== 'conf.instances.json' || !fs.existsSync(filePath)) continue;
-
-          let instances;
-          try {
-            instances = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-          } catch {
-            logger.warn(`Skipping invalid JSON file: ${filePath}`);
-            continue;
-          }
-
-          if (!Array.isArray(instances)) continue;
-
-          let updated = false;
-          for (const instance of instances) {
-            if (!instance || typeof instance !== 'object') continue;
-            if (!instance.image || typeof instance.image !== 'string') continue;
-            if (!instance.image.startsWith('underpost/')) continue;
+      // ── Canonical version files: delegate to bumpp (package.json, package-lock.json,
+      //    engine-private/conf/**/package.json). bumpp owns lockfile semantics (root version
+      //    + packages[''].version) so we don't reimplement them. ──
+      const { versionBump } = await import('bumpp');
+      const bumppResult = await versionBump({
+        release: newVersion,
+        files: [
+          'package.json',
+          'package-lock.json',
+          ...(fs.existsSync('./engine-private/conf') ? ['engine-private/conf/**/package.json'] : []),
+        ],
+        commit: false,
+        tag: false,
+        push: false,
+        confirm: false,
+        recursive: false,
+        ignoreScripts: true,
+        dry: dryRun,
+      });
+      logger.info(`bumpp updated ${bumppResult?.files?.length ?? 0} canonical file(s).`);
 
-            const baseImage = instance.image.split('@')[0].split(':')[0];
-            const nextImage = `${baseImage}:v${newVersion}`;
-            if (instance.image !== nextImage) {
-              instance.image = nextImage;
-              updated = true;
-            }
-          }
+      // ── Auxiliary files: anchored-regex walker over VERSION_BUMP_TARGETS. ──
+      const report = bumpAuxiliaryFiles(version, newVersion, { dryRun });
+      printBumpReport(report, { dryRun });
 
-          if (updated) fs.writeFileSync(filePath, JSON.stringify(instances, null, 2), 'utf8');
-        }
+      if (dryRun) {
+        logger.info('Dry-run complete. No files modified. Re-run without --dry-run to apply.');
+        return { from: version, to: newVersion, files: report.map((r) => r.file), dryRun: true };
       }
 
-      fs.writeFileSync(
-        `./src/index.js`,
-        fs.readFileSync(`./src/index.js`, 'utf8').replaceAll(`${version}`, `${newVersion}`),
-        'utf8',
-      );
+      // ── Downstream regenerations and manifest sync (unchanged from previous flow). ──
       shellExec(`node bin/deploy cli-docs ${version} ${newVersion}`);
       shellExec(`node bin/deploy update-dependencies`);
       shellExec(`node bin/build dd`);
@@ -206,6 +363,7 @@ class UnderpostRelease {
       shellExec(`sudo rm -rf ./engine-private/conf/dd-default`);
       shellExec(`node bin cron --kubeadm --setup-start --git`); // --apply
       shellExec(`node bin cmt --changelog-build`);
+      return { from: version, to: newVersion, files: report.map((r) => r.file), dryRun: false };
     },
 
     /**

package/src/cli/repository.js

@@ -401,6 +401,7 @@ class UnderpostRepository {
 
     /**
      * Retrieves the message of the last Git commit.
+     * @param {number} [skip=0] - Number of commits to skip from HEAD (0 = most recent).
      * @returns {string} The last commit message.
      * @memberof UnderpostRepository
      */
@@ -949,6 +950,7 @@ Prevent build private config repo.`,
     /**
      * Retrieves the Git commit history.
      * @param {number} [sinceCommit=1] - The number of recent commits to retrieve.
+     * @param {string} [repoPath='.'] - The path to the repository.
      * @returns {Array<{hash: string, message: string, files: string}>} An array of commit objects with hash, message, and files.
      * @memberof UnderpostRepository
      */
@@ -1006,11 +1008,14 @@ Prevent build private config repo.`,
             const host = 'default.net';
             const path = '/';
             DefaultConf.server[host][path].valkey = {
-              port: 6379,
-              host: 'valkey-service.default.svc.cluster.local',
+              port: 'env:VALKEY_PORT:int:6379',
+              host: 'env:VALKEY_HOST:127.0.0.1',
             };
-            // mongodb-0.mongodb-service
-            DefaultConf.server[host][path].db.host = 'mongodb://mongodb-service:27017';
+            DefaultConf.server[host][path].db.host = 'env:DB_HOST:mongodb://127.0.0.1:27017';
+            DefaultConf.server[host][path].db.replicaSet = 'env:DB_REPLICA_SET:rs0';
+            DefaultConf.server[host][path].db.authSource = 'env:DB_AUTH_SOURCE:admin';
+            DefaultConf.server[host][path].db.user = 'env:DB_USER:';
+            DefaultConf.server[host][path].db.password = 'env:DB_PASSWORD:';
             defaultConf = true;
             break;
           }
@@ -1270,19 +1275,10 @@ Prevent build private config repo.`,
     },
 
     /**
-     * Returns metadata about unpushed commits in a git repository.
-     * Fetches from origin, then counts commits ahead of the remote branch.
-     * @param {string} [repoPath='.'] - Path to the git repository.
-     * @param {number} [fallback=1] - Value to return as `count` when no unpushed commits are detected.
-     * @returns {{ count: number, branch: string, hasUnpushed: boolean }} Unpush metadata.
-     * @memberof UnderpostRepository
-     */
-    /**
-     * Checks whether a remote Git repository URL is reachable.
-     * Uses `git ls-remote` with `|| true` so the process always exits 0.
-     * Injects `GITHUB_TOKEN` into GitHub HTTPS URLs when available.
-     * @param {string} url - Full HTTPS clone URL to test (e.g. "https://github.com/org/repo.git").
-     * @returns {boolean} `true` when the remote responded with at least one ref hash.
+     * Resolves a Git remote URL, normalizing short-form owner/repo references to full
+     * GitHub HTTPS URLs and injecting GITHUB_TOKEN when available.
+     * @param {string} url - The repository URL or short-form (e.g. "owner/repo" or full HTTPS URL).
+     * @returns {string} The resolved (and optionally authenticated) HTTPS URL.
      * @memberof UnderpostRepository
      */
     resolveAuthUrl(url) {
@@ -1300,20 +1296,36 @@ Prevent build private config repo.`,
       }
       return normalized;
     },
-
+    /**
+     * Checks whether a remote Git repository URL is reachable.
+     * Uses `silentOnError` so a non-reachable remote returns false instead of throwing.
+     * Injects `GITHUB_TOKEN` into GitHub HTTPS URLs when available.
+     * @param {string} url - Full HTTPS clone URL to test (e.g. "https://github.com/org/repo.git").
+     * @returns {boolean} `true` when the remote responded with at least one ref hash.
+     * @memberof UnderpostRepository
+     */
     isRemoteRepo(url) {
       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 || true`, {
+      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git 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);
     },
 
+    /**
+     * Returns metadata about unpushed commits in a git repository.
+     * Fetches from origin, then counts commits ahead of the remote branch.
+     * @param {string} [repoPath='.'] - Path to the git repository.
+     * @param {number} [fallback=1] - Value to return as `count` when no unpushed commits are detected.
+     * @returns {{ count: number, branch: string, hasUnpushed: boolean }} Unpush metadata.
+     * @memberof UnderpostRepository
+     */
     getUnpushedCount(repoPath = '.', fallback = 1) {
       const branch = shellExec(`cd ${repoPath} && git branch --show-current`, {
         stdout: true,
@@ -1353,19 +1365,6 @@ Prevent build private config repo.`,
         .trim()
         .replaceAll('] - ', '] ');
     },
-
-    /**
-     * Manages a cron-backup Git repository: clone, pull, commit, or push.
-     * Resolves the repository path as `../<repoName>` relative to the CWD.
-     * Requires the `GITHUB_USERNAME` environment variable to be set.
-     * @param {object} params
-     * @param {string} params.repoName - Repository name (e.g. `engine-cyberia-cron-backups`).
-     * @param {'clone'|'pull'|'commit'|'push'} params.operation - Git operation to perform.
-     * @param {string} [params.message=''] - Commit message (used by the `commit` operation).
-     * @param {boolean} [params.forceClone=false] - Remove existing clone before re-cloning.
-     * @returns {boolean} `true` on success, `false` if GITHUB_USERNAME is unset or on error.
-     * @memberof UnderpostRepository
-     */
     /**
      * Initializes a git repository at the given path and configures user identity
      * from environment variables (`GITHUB_USERNAME` / `GITHUB_EMAIL`).
@@ -1387,9 +1386,10 @@ Prevent build private config repo.`,
       shellExec(`cd "${repoPath}" && git config user.email '${gitEmail}'`);
 
       if (origin) {
-        const currentRemote = shellExec(`cd "${repoPath}" && git remote get-url origin 2>/dev/null || true`, {
+        const currentRemote = shellExec(`cd "${repoPath}" && git remote get-url origin`, {
           stdout: true,
           silent: true,
+          silentOnError: true,
         }).trim();
         if (!currentRemote) {
           shellExec(`cd "${repoPath}" && git remote add origin "${origin}"`);
@@ -1398,7 +1398,18 @@ Prevent build private config repo.`,
         }
       }
     },
-
+    /**
+     * Manages a cron-backup Git repository: clone, pull, commit, or push.
+     * Resolves the repository path as `../<repoName>` relative to the CWD.
+     * Requires the `GITHUB_USERNAME` environment variable to be set.
+     * @param {object} params
+     * @param {string} params.repoName - Repository name (e.g. `engine-cyberia-cron-backups`).
+     * @param {'clone'|'pull'|'commit'|'push'} params.operation - Git operation to perform.
+     * @param {string} [params.message=''] - Commit message (used by the `commit` operation).
+     * @param {boolean} [params.forceClone=false] - Remove existing clone before re-cloning.
+     * @returns {boolean} `true` on success, `false` if GITHUB_USERNAME is unset or on error.
+     * @memberof UnderpostRepository
+     */
     manageBackupRepo({ repoName, operation, message = '', forceClone = false }) {
       try {
         const username = process.env.GITHUB_USERNAME;
@@ -1602,6 +1613,52 @@ Prevent build private config repo.`,
         logger.info('engine-private in /home/dd removed');
       }
     },
+
+    /**
+     * Resolves the GitHub repository for a given instance runtime by scanning
+     * every `conf.instances.json` listed in `./engine-private/deploy/dd.router`.
+     *
+     * Resolution order:
+     *  1. If `runtime` is falsy, returns `${GITHUB_USERNAME}/engine`.
+     *  2. Iterates each deploy ID found in `dd.router` and looks for an instance
+     *     whose `runtime` field matches the supplied value.
+     *  3. When a match is found, returns `instance.metadata.repository`.
+     *  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'`).
+     * @returns {string} The resolved `owner/repo` string.
+     * @memberof UnderpostRepository
+     */
+    resolveInstanceRepo(runtime = '') {
+      const fallback = `${process.env.GITHUB_USERNAME}/engine`;
+      if (!runtime) return fallback;
+      const ddRouter = './engine-private/deploy/dd.router';
+      const deployIds = fs.existsSync(ddRouter)
+        ? fs
+            .readFileSync(ddRouter, 'utf8')
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : [];
+      for (const deployId of deployIds) {
+        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);
+          if (match && match.metadata && match.metadata.repository) {
+            logger.info(`[resolveInstanceRepo] resolved from ${confPath}`, {
+              runtime,
+              repo: match.metadata.repository,
+            });
+            return match.metadata.repository;
+          }
+        } catch (err) {
+          logger.warn(`[resolveInstanceRepo] failed to parse ${confPath}: ${err.message}`);
+        }
+      }
+      return fallback;
+    },
   };
 }