cyberia 3.0.3 → 3.2.5

package/src/cli/repository.js

@@ -4,18 +4,27 @@
  * @namespace UnderpostRepository
  */
 
-import { commitData } from '../client/components/core/CommonJs.js';
 import dotenv from 'dotenv';
+import { commitData } from '../client/components/core/CommonJs.js';
 import { pbcopy, shellCd, shellExec } from '../server/process.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 import fs from 'fs-extra';
-import { getNpmRootPath } from '../server/conf.js';
-import { Config } from '../server/conf.js';
+import {
+  getNpmRootPath,
+  Config,
+  loadConf,
+  readConfJson,
+  getConfFilePath,
+  loadReplicas,
+  loadConfServerJson,
+  getDataDeploy,
+  buildReplicaId,
+  writeEnv,
+} from '../server/conf.js';
+import { buildClient } from '../server/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
-dotenv.config();
-
 const logger = loggerFactory(import.meta);
 
 const diffCmd = `--no-pager show -U0 -w --word-diff=color --word-diff-regex='[^[:space:]]' --color=always`;
@@ -37,8 +46,8 @@ class UnderpostRepository {
      * @param {boolean} [options.g8=false] - If true, uses the .g8 extension.
      * @memberof UnderpostRepository
      */
-    clone(gitUri = `${process.env.GITHUB_USERNAME}/pwa-microservices-template`, options = { bare: false, G8: false }) {
-      const gExtension = options.G8 === true ? '.g8' : '.git';
+    clone(gitUri = `${process.env.GITHUB_USERNAME}/pwa-microservices-template`, options = { bare: false, g8: false }) {
+      const gExtension = options.g8 === true ? '.g8' : '.git';
       const repoName = gitUri.split('/').pop();
       if (fs.existsSync(`./${repoName}`)) fs.removeSync(`./${repoName}`);
       shellExec(
@@ -54,16 +63,16 @@ class UnderpostRepository {
      * Pulls updates from a GitHub repository.
      * @param {string} [repoPath='./'] - The local path to the repository.
      * @param {string} [gitUri=`${process.env.GITHUB_USERNAME}/pwa-microservices-template`] - The URI of the GitHub repository.
-     * @param {object} [options={ G8: false }] - Pulling options.
+     * @param {object} [options={ g8: false }] - Pulling options.
      * @param {boolean} [options.g8=false] - If true, uses the .g8 extension.
      * @memberof UnderpostRepository
      */
     pull(
       repoPath = './',
       gitUri = `${process.env.GITHUB_USERNAME}/pwa-microservices-template`,
-      options = { G8: false },
+      options = { g8: false },
     ) {
-      const gExtension = options.G8 === true ? '.g8' : '.git';
+      const gExtension = options.g8 === true ? '.g8' : '.git';
       shellExec(
         `cd ${repoPath} && git pull https://${
           process.env.GITHUB_TOKEN ? `${process.env.GITHUB_TOKEN}@` : ''
@@ -88,6 +97,7 @@ class UnderpostRepository {
      * @param {boolean} [options.cached=false] - If true, commits only staged changes.
      * @param {number} [options.log=0] - If greater than 0, shows the last N commits with diffs.
      * @param {boolean} [options.lastMsg=0] - If greater than 0, copies or show the last last single n commit message to clipboard.
+     * @param {boolean} [options.unpush=false] - If true with --log, automatically detects unpushed commits ahead of remote and uses that count.
      * @param {string} [options.deployId=''] - An optional deploy ID to include in the commit message.
      * @param {string} [options.hashes=''] - If provided with diff option, shows the diff between two hashes.
      * @param {string} [options.extension=''] - If provided with diff option, filters the diff by this file extension.
@@ -118,15 +128,64 @@ class UnderpostRepository {
         changelogBuild: false,
         changelogMinVersion: '',
         changelogNoHash: false,
+        unpush: false,
+        b: false,
+        p: undefined,
+        bc: '',
+        isRemoteRepo: '',
       },
     ) {
       if (!repoPath) repoPath = '.';
 
+      if (options.isRemoteRepo) {
+        const accessible = Underpost.repo.isRemoteRepo(options.isRemoteRepo);
+        console.log(accessible);
+        return;
+      }
+
+      if (options.bc) {
+        console.log(
+          shellExec(`cd ${repoPath} && git for-each-ref --contains ${options.bc} --format='%(refname:short)'`, {
+            stdout: true,
+            silent: true,
+            disableLog: true,
+          }).trim(),
+        );
+        return;
+      }
+
+      if (options.p !== undefined) {
+        const branch =
+          options.p === true
+            ? shellExec(`cd ${repoPath} && git branch --show-current`, {
+                stdout: true,
+                silent: true,
+                disableLog: true,
+              }).trim()
+            : options.p;
+        console.log(
+          shellExec(`cd ${repoPath} && git --no-pager reflog show refs/heads/${branch}`, {
+            stdout: true,
+            silent: true,
+            disableLog: true,
+          }).trim(),
+        );
+        return;
+      }
+
+      if (options.b) {
+        const currentBranch = shellExec(`cd ${repoPath} && git branch --show-current`, {
+          stdout: true,
+          silent: true,
+          disableLog: true,
+        }).trim();
+        if (options.copy) pbcopy(currentBranch);
+        else console.log(currentBranch);
+        return;
+      }
+
       if (options.changelog !== undefined || options.changelogBuild) {
-        const ciIntegrationPrefix = 'ci(package-pwa-microservices-';
-        const ciIntegrationVersionPrefix = 'New release v:';
         const releaseMatch = 'New release v:';
-
         // Helper: parse [<tag>] commits into grouped sections
         const buildSectionChangelog = (commits) => {
           const groups = {};
@@ -253,24 +312,13 @@ 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 or since last release
+          // --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) : 500;
+          const scanLimit = hasExplicitCount ? parseInt(options.changelog) : 1;
           const allCommits = fetchHistory(scanLimit);
 
-          let commits;
-          if (!hasExplicitCount) {
-            // No explicit count: find commits up to the last CI integration boundary
-            const ciIndex = allCommits.findIndex(
-              (c) => c.message.startsWith(ciIntegrationPrefix) && !c.message.match(ciIntegrationVersionPrefix),
-            );
-            commits = ciIndex >= 0 ? allCommits.slice(0, ciIndex) : allCommits;
-          } else {
-            commits = allCommits;
-          }
-
-          const sections = buildVersionSections(commits);
+          const sections = buildVersionSections(allCommits);
           let changelog = renderSections(sections);
           console.log(changelog || `No changelog entries found.\n`);
         }
@@ -297,17 +345,25 @@ class UnderpostRepository {
         else console.log('Diff command:', _diffCmd);
         return;
       }
-      if (options.log) {
-        const history = Underpost.repo.getHistory(options.log);
+      if (options.log || options.unpush) {
+        if (options.unpush) {
+          const { count, hasUnpushed } = Underpost.repo.getUnpushedCount(repoPath);
+          if (!hasUnpushed) {
+            logger.warn('No unpushed commits found');
+            return;
+          }
+          options.log = count;
+        }
+        const history = Underpost.repo.getHistory(options.log, repoPath);
         const chainCmd = history
           .reverse()
-          .map((commitData, i) => `${i === 0 ? '' : ' && '}git ${diffCmd} ${commitData.hash}`)
+          .map((commitData, i) => `${i === 0 ? '' : ' && '}git -C ${repoPath} ${diffCmd} ${commitData.hash}`)
           .join('');
         if (history[0]) {
           let index = history.length;
           for (const commit of history) {
             console.log(
-              shellExec(`git show -s --format=%ci ${commit.hash}`, {
+              shellExec(`cd ${repoPath} && git show -s --format=%ci ${commit.hash}`, {
                 stdout: true,
                 silent: true,
                 disableLog: true,
@@ -316,7 +372,7 @@ class UnderpostRepository {
             console.log(`${index}`.magenta, commit.hash.yellow, commit.message);
             index--;
             console.log(
-              shellExec(`git show --name-status --pretty="" ${commit.hash}`, {
+              shellExec(`cd ${repoPath} && git show --name-status --pretty="" ${commit.hash}`, {
                 stdout: true,
                 silent: true,
                 disableLog: true,
@@ -360,7 +416,7 @@ class UnderpostRepository {
      * Pushes commits to a remote GitHub repository.
      * @param {string} [repoPath='./'] - The local path to the repository.
      * @param {string} [gitUri=`${process.env.GITHUB_USERNAME}/pwa-microservices-template`] - The URI of the GitHub repository.
-     * @param {object} [options={ f: false, G8: false }] - Push options.
+     * @param {object} [options={ f: false, g8: false }] - Push options.
      * @param {boolean} [options.f=false] - If true, forces the push.
      * @param {boolean} [options.g8=false] - If true, uses the .g8 extension.
      * @memberof UnderpostRepository
@@ -368,9 +424,9 @@ class UnderpostRepository {
     push(
       repoPath = './',
       gitUri = `${process.env.GITHUB_USERNAME}/pwa-microservices-template`,
-      options = { f: false, G8: false },
+      options = { f: false, g8: false },
     ) {
-      const gExtension = options.G8 === true ? '.g8' : '.git';
+      const gExtension = options.g8 === true ? '.g8' : '.git';
       shellExec(
         `cd ${repoPath} && git push https://${process.env.GITHUB_TOKEN}@github.com/${gitUri}${gExtension}${
           options?.f === true ? ' --force' : ''
@@ -403,6 +459,7 @@ class UnderpostRepository {
      * @param {boolean} [options.cleanTemplate=false] - If true, cleans the pwa-microservices-template build directory.
      * @param {boolean} [options.build=false] - If true, builds the deployment to pwa-microservices-template (requires deployId).
      * @param {boolean} [options.syncConf=false] - If true, syncs configuration to private repositories (requires deployId).
+     * @param {boolean} [options.syncStart=false] - If true, syncs start scripts in deploy ID package.json with root package.json.
      * @param {boolean} [options.defaultConf=false] - If true, updates the default configuration file (requires deployId).
      * @param {string} [options.confWorkflowId=''] - If provided, uses this configuration workflow ID.
      * @returns {Promise<boolean>} A promise that resolves when the initialization is complete.
@@ -420,6 +477,7 @@ class UnderpostRepository {
         cleanTemplate: false,
         build: false,
         syncConf: false,
+        syncStart: false,
         defaultConf: false,
         confWorkflowId: '',
       },
@@ -448,6 +506,13 @@ class UnderpostRepository {
 
           if (options.deployId) {
             let deployId = options.deployId;
+
+            // Handle sync-start operation (before dd- prefix normalization to support 'dd' special case)
+            if (options.syncStart) {
+              shellExec(`node bin/deploy sync-start ${deployId}`);
+              return resolve(true);
+            }
+
             if (!deployId.startsWith('dd-')) deployId = `dd-${deployId}`;
             // Handle purge operation
             if (options.purge) {
@@ -531,14 +596,9 @@ class UnderpostRepository {
                   logger.info(`Created repository directory: ${repo.path}`);
                 }
 
-                // Initialize git repository
-                shellExec(`cd ${repo.path} && git init`, { disableLog: false });
-                logger.info(`Initialized git repository in: ${repo.path}`);
-
-                // Add remote origin
                 const remoteUrl = `https://${token ? `${token}@` : ''}github.com/${username}/${repo.name}.git`;
-                shellExec(`cd ${repo.path} && git remote add origin ${remoteUrl}`, { disableLog: false });
-                logger.info(`Added remote origin for: ${repo.name}`);
+                UnderpostRepository.API.initLocalRepo({ path: repo.path, origin: remoteUrl });
+                logger.info(`Initialized git repository with remote: ${repo.name}`);
               }
             }
             return resolve(true);
@@ -547,7 +607,6 @@ class UnderpostRepository {
             const npmRoot = getNpmRootPath();
             const underpostRoot = options?.dev === true ? '.' : `${npmRoot}/underpost`;
             const destFolder = `./${projectName}`;
-            logger.info('Note: This process may take several minutes to complete');
             logger.info('build app', { destFolder });
             if (fs.existsSync(destFolder)) fs.removeSync(destFolder);
             fs.mkdirSync(destFolder, { recursive: true });
@@ -558,7 +617,8 @@ class UnderpostRepository {
                 fs.readFileSync(`${underpostRoot}/.dockerignore`, 'utf8'),
                 'utf8',
               );
-              shellExec(`cd ${destFolder} && git init && git add . && git commit -m "Base template implementation"`);
+              UnderpostRepository.API.initLocalRepo({ path: destFolder });
+              shellExec(`cd ${destFolder} && git add . && git commit -m "Base template implementation"`);
             }
             shellExec(`cd ${destFolder} && npm run build`);
             shellExec(`cd ${destFolder} && npm run dev`);
@@ -572,6 +632,216 @@ class UnderpostRepository {
       });
     },
 
+    /**
+     * Builds client assets, single replicas, and/or syncs environment ports.
+     * @param {string} [deployId='dd-default'] - The deployment ID.
+     * @param {string} [subConf=''] - The sub-configuration for the build.
+     * @param {string} [host=''] - Comma-separated hosts to filter the build.
+     * @param {string} [path=''] - Comma-separated paths to filter the build.
+     * @param {object} [options] - Build options.
+     * @param {boolean} [options.syncEnvPort=false] - If true, syncs environment port assignments across all deploy IDs.
+     * @param {boolean} [options.singleReplica=false] - If true, builds single replica folders instead of full client.
+     * @param {boolean} [options.buildZip=false] - If true, creates zip files of the builds.
+     * @param {boolean} [options.liteBuild=false] - If true, skips full build (default is full build).
+     * @param {boolean} [options.iconsBuild=false] - If true, builds icons.
+     * @returns {Promise<boolean>} A promise that resolves when the build is complete.
+     * @memberof UnderpostRepository
+     */
+    client(
+      deployId = 'dd-default',
+      subConf = '',
+      host = '',
+      path = '',
+      options = {
+        syncEnvPort: false,
+        singleReplica: false,
+        buildZip: false,
+        liteBuild: false,
+        iconsBuild: false,
+      },
+    ) {
+      return new Promise(async (resolve, reject) => {
+        try {
+          // Handle singleReplica operation (must run before syncEnvPort to ensure replica dirs exist)
+          if (options.singleReplica) {
+            const replicaPath = path;
+            if (!deployId || !host || !replicaPath) {
+              logger.error('client --single-replica requires deploy-id, host, and path arguments');
+              return reject(false);
+            }
+            const serverConf = loadReplicas(
+              deployId,
+              loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
+            );
+
+            if (serverConf[host][replicaPath].replicas) {
+              {
+                let replicaIndex = -1;
+                for (const replica of serverConf[host][replicaPath].replicas) {
+                  replicaIndex++;
+                  const replicaDeployId = `${deployId}-${serverConf[host][replicaPath].replicas[replicaIndex].slice(1)}`;
+                  await fs.copy(`./engine-private/conf/${deployId}`, `./engine-private/replica/${replicaDeployId}`);
+                  fs.writeFileSync(
+                    `./engine-private/replica/${replicaDeployId}/package.json`,
+                    fs
+                      .readFileSync(`./engine-private/replica/${replicaDeployId}/package.json`, 'utf8')
+                      .replaceAll(`${deployId}`, `${replicaDeployId}`),
+                    'utf8',
+                  );
+                  const replicaFolder = `./engine-private/replica/${replicaDeployId}`;
+                  for (const envFile of ['.env.production', '.env.development', '.env.test']) {
+                    const envFilePath = `${replicaFolder}/${envFile}`;
+                    if (fs.existsSync(envFilePath)) {
+                      fs.writeFileSync(
+                        envFilePath,
+                        fs
+                          .readFileSync(envFilePath, 'utf8')
+                          .replaceAll(`DEPLOY_ID=${deployId}`, `DEPLOY_ID=${replicaDeployId}`),
+                        'utf8',
+                      );
+                    }
+                  }
+                }
+              }
+              {
+                let replicaIndex = -1;
+                for (const replica of serverConf[host][replicaPath].replicas) {
+                  replicaIndex++;
+                  const replicaDeployId = `${deployId}-${serverConf[host][replicaPath].replicas[replicaIndex].slice(1)}`;
+                  let replicaServerConf = JSON.parse(
+                    fs.readFileSync(`./engine-private/replica/${replicaDeployId}/conf.server.json`, 'utf8'),
+                  );
+
+                  const singleReplicaConf = replicaServerConf[host][replicaPath];
+                  singleReplicaConf.replicas = undefined;
+                  singleReplicaConf.singleReplica = undefined;
+
+                  replicaServerConf = {};
+                  replicaServerConf[host] = {};
+                  replicaServerConf[host][replica] = singleReplicaConf;
+
+                  fs.writeFileSync(
+                    `./engine-private/replica/${replicaDeployId}/conf.server.json`,
+                    JSON.stringify(replicaServerConf, null, 4),
+                    'utf8',
+                  );
+                }
+              }
+            }
+            if (!options.syncEnvPort) return resolve(true);
+          }
+
+          // Handle syncEnvPort operation
+          if (options.syncEnvPort) {
+            const dataDeploy = await getDataDeploy({ disableSyncEnvPort: true });
+            const dataEnv = [
+              { env: 'production', port: 3000 },
+              { env: 'development', port: 4000 },
+              { env: 'test', port: 5000 },
+            ];
+            let portOffset = 0;
+            const singleReplicaPortOffsets = {};
+            for (const deployIdObj of dataDeploy) {
+              const { deployId } = deployIdObj;
+              const baseConfPath = fs.existsSync(`./engine-private/replica/${deployId}`)
+                ? `./engine-private/replica`
+                : `./engine-private/conf`;
+
+              const effectivePortOffset =
+                singleReplicaPortOffsets[deployId] !== undefined ? singleReplicaPortOffsets[deployId] : portOffset;
+
+              let skipDeploy = false;
+              for (const envInstanceObj of dataEnv) {
+                const envPath = `${baseConfPath}/${deployId}/.env.${envInstanceObj.env}`;
+                if (!fs.existsSync(envPath)) {
+                  logger.warn(`Skipping ${deployId}: ${envPath} not found`);
+                  skipDeploy = true;
+                  break;
+                }
+                const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
+                envObj.PORT = `${envInstanceObj.port + effectivePortOffset}`;
+                writeEnv(envPath, envObj);
+              }
+
+              if (skipDeploy) continue;
+              if (singleReplicaPortOffsets[deployId] !== undefined) continue;
+
+              const serverConf = loadReplicas(
+                deployId,
+                loadConfServerJson(`${baseConfPath}/${deployId}/conf.server.json`),
+              );
+              for (const host of Object.keys(serverConf)) {
+                let deferredSingleReplicaSlots = [];
+                for (const path of Object.keys(serverConf[host])) {
+                  if (serverConf[host][path].singleReplica && serverConf[host][path].replicas) {
+                    deferredSingleReplicaSlots.push({
+                      replicas: serverConf[host][path].replicas,
+                      peer: !!serverConf[host][path].peer,
+                    });
+                    continue;
+                  }
+                  portOffset++;
+                  if (serverConf[host][path].peer) portOffset++;
+                }
+                for (const slot of deferredSingleReplicaSlots) {
+                  for (const replica of slot.replicas) {
+                    const replicaDeployId = buildReplicaId({ deployId, replica });
+                    singleReplicaPortOffsets[replicaDeployId] = portOffset;
+                    portOffset++;
+                    if (slot.peer) portOffset++;
+                  }
+                }
+              }
+            }
+            return resolve(true);
+          }
+
+          // Handle buildFullClient operation (default)
+          {
+            const { deployId: resolvedDeployId } = loadConf(deployId, subConf ?? '');
+
+            let argHost = host ? host.split(',') : [];
+            let argPath = path ? path.split(',') : [];
+            let deployIdSingleReplicas = [];
+            let singleReplicaHosts = [];
+            const serverConf = resolvedDeployId
+              ? readConfJson(resolvedDeployId, 'server', { loadReplicas: true })
+              : Config.default.server;
+            const confFilePath = resolvedDeployId ? getConfFilePath(resolvedDeployId, 'server') : null;
+            const originalConfBackup = confFilePath ? fs.readFileSync(confFilePath, 'utf8') : null;
+            for (const host of Object.keys(serverConf)) {
+              for (const path of Object.keys(serverConf[host])) {
+                if (argHost.length && argPath.length && (!argHost.includes(host) || !argPath.includes(path))) {
+                  delete serverConf[host][path];
+                } else {
+                  if (serverConf[host][path].singleReplica && serverConf[host][path].replicas) {
+                    singleReplicaHosts.push({ host, path });
+                    deployIdSingleReplicas = deployIdSingleReplicas.concat(
+                      serverConf[host][path].replicas.map((replica) =>
+                        buildReplicaId({ deployId: resolvedDeployId, replica }),
+                      ),
+                    );
+                  }
+                }
+              }
+            }
+            await buildClient({
+              buildZip: options.buildZip || false,
+              fullBuild: options.liteBuild ? false : true,
+              iconsBuild: options.iconsBuild || false,
+            });
+            for (const replicaDeployId of deployIdSingleReplicas) await Underpost.repo.client(replicaDeployId);
+
+            return resolve(true);
+          }
+        } catch (error) {
+          console.log(error);
+          logger.error(error, error.stack);
+          return reject(false);
+        }
+      });
+    },
+
     /**
      * Gets a list of deleted files from a Git repository.
      * @param {string} [path='.'] - The path to the repository.
@@ -650,8 +920,8 @@ Prevent build private config repo.`,
      * @returns {Array<{hash: string, message: string, files: string}>} An array of commit objects with hash, message, and files.
      * @memberof UnderpostRepository
      */
-    getHistory(sinceCommit = 1) {
-      return shellExec(`git log -1 --pretty=format:"%h %s" -n ${sinceCommit}`, {
+    getHistory(sinceCommit = 1, repoPath = '.') {
+      return shellExec(`cd ${repoPath} && git log -1 --pretty=format:"%h %s" -n ${sinceCommit}`, {
         stdout: true,
         silent: true,
         disableLog: true,
@@ -666,7 +936,7 @@ Prevent build private config repo.`,
         })
         .filter((line) => line.hash)
         .map((line) => {
-          line.files = shellExec(`git show --name-status --pretty="" ${line.hash}`, {
+          line.files = shellExec(`cd ${repoPath} && git show --name-status --pretty="" ${line.hash}`, {
             stdout: true,
             silent: true,
             disableLog: true,
@@ -720,25 +990,14 @@ Prevent build private config repo.`,
         DefaultConf.client = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.client.json`, 'utf8'));
         DefaultConf.server = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
         DefaultConf.ssr = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.ssr.json`, 'utf8'));
-        // DefaultConf.cron = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.cron.json`, 'utf8'));
-
-        for (const host of Object.keys(DefaultConf.server)) {
-          for (const path of Object.keys(DefaultConf.server[host])) {
-            DefaultConf.server[host][path].db = defaultServer.db;
-            DefaultConf.server[host][path].mailer = defaultServer.mailer;
-
-            delete DefaultConf.server[host][path]._wp_client;
-            delete DefaultConf.server[host][path]._wp_git;
-            delete DefaultConf.server[host][path]._wp_directory;
-            delete DefaultConf.server[host][path].wp;
-            delete DefaultConf.server[host][path].git;
-            delete DefaultConf.server[host][path].directory;
-          }
-        }
       } else
         logger.warn(
           `Deploy ID configuration not found: ./engine-private/conf/${deployId}, using default configuration.`,
         );
+
+      // Serialize the configuration into the conf.*.js manifest file.
+      // env: references from JSON configs are preserved as 'env:KEY' strings.
+      // At runtime, resolveConfSecrets() in conf.js resolves them via process.env.
       const sepRender = '/**/';
       const confRawPaths = fs.readFileSync('./conf.js', 'utf8').split(sepRender);
       confRawPaths[1] = `${JSON.stringify(DefaultConf)};`;
@@ -924,6 +1183,393 @@ Prevent build private config repo.`,
 
       return copiedFiles;
     },
+
+    /**
+     * 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 {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;
+      const ghAvailable = shellExec('command -v gh 2>/dev/null', {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+      }).trim();
+
+      if (ghAvailable) {
+        let cmd = `gh workflow run ${workflowFile} --repo ${repo} --ref ${ref}`;
+        for (const [key, value] of Object.entries(inputs)) {
+          if (value !== undefined && value !== '') {
+            const escaped = String(value).replace(/'/g, "'\\''");
+            cmd += ` -f ${key}='${escaped}'`;
+          }
+        }
+        shellExec(cmd);
+      } else {
+        let token = process.env.GITHUB_TOKEN;
+        if (!token) {
+          const envPath = `${getNpmRootPath()}/underpost/.env`;
+          if (fs.existsSync(envPath) && fs.statSync(envPath).isFile()) {
+            const envVars = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
+            token = envVars.GITHUB_TOKEN;
+          }
+        }
+        if (!token) {
+          logger.error('GITHUB_TOKEN is required for workflow dispatch (gh CLI not available)');
+          return;
+        }
+        const payload = { ref };
+        if (Object.keys(inputs).length > 0) payload.inputs = inputs;
+        const payloadJson = JSON.stringify(payload).replace(/'/g, "'\\''");
+        shellExec(
+          `curl -s -f -X POST ` +
+            `-H "Accept: application/vnd.github.v3+json" ` +
+            `-H "Authorization: token ${token}" ` +
+            `"https://api.github.com/repos/${repo}/actions/workflows/${workflowFile}/dispatches" ` +
+            `-d '${payloadJson}'`,
+        );
+      }
+      logger.info('Dispatched workflow', `${repo} -> ${workflowFile}`, inputs.job ? `(job: ${inputs.job})` : '');
+    },
+
+    /**
+     * 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.
+     * @memberof UnderpostRepository
+     */
+    resolveAuthUrl(url) {
+      if (!url) return url;
+      // Normalize short form "owner/repo" → full GitHub HTTPS URL
+      let normalized = url;
+      if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('git@')) {
+        normalized = `https://github.com/${url}`;
+      }
+      if (process.env.GITHUB_TOKEN && normalized.startsWith('https://github.com/')) {
+        return normalized.replace(
+          'https://github.com/',
+          `https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/`,
+        );
+      }
+      return normalized;
+    },
+
+    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`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+      });
+      logger.info('isRemoteRepo', { url, raw: (raw || '').slice(0, 120) });
+      return typeof raw === 'string' && /^[0-9a-f]{40}\t/m.test(raw);
+    },
+
+    getUnpushedCount(repoPath = '.', fallback = 1) {
+      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 });
+      const raw = shellExec(`cd ${repoPath} && git rev-list --count origin/${branch}..HEAD 2>/dev/null`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+      }).trim();
+      const count = parseInt(raw);
+      const hasUnpushed = !isNaN(count) && count > 0;
+      return { count: hasUnpushed ? count : fallback, branch, hasUnpushed };
+    },
+
+    /**
+     * Sanitizes a markdown changelog string into a compact message format.
+     * Strips date headers, converts section tags to `[tag]` prefixes, removes bullet markers and special characters.
+     * @param {string} message - The raw markdown changelog output.
+     * @returns {string} The sanitized single-line or multi-line compact message.
+     * @memberof UnderpostRepository
+     */
+    sanitizeChangelogMessage(message) {
+      if (!message) return '';
+      return message
+        .replace(/^##\s+\d{4}-\d{2}-\d{2}\s*/gm, '')
+        .replace(/^###\s+(\S+)\s*/gm, '[$1] ')
+        .replace(/^- /gm, '')
+        .replaceAll('"', '')
+        .replaceAll('`', '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .join('\n')
+        .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`).
+     * Safe to call on an already-initialized repo — only runs `git init` when
+     * `.git` is absent and always ensures user.name / user.email are set.
+     * @param {object} opts
+     * @param {string} opts.path       - Absolute or relative path to the repository.
+     * @param {string} [opts.origin]   - If provided, sets or updates git remote `origin`.
+     * @memberof UnderpostRepository
+     */
+    initLocalRepo({ path: repoPath, origin }) {
+      const gitUsername = process.env.GITHUB_USERNAME || 'underpostnet';
+      const gitEmail = process.env.GITHUB_EMAIL || `development@underpost.net`;
+
+      if (!fs.existsSync(`${repoPath}/.git`)) {
+        shellExec(`cd "${repoPath}" && git init`);
+      }
+      shellExec(`cd "${repoPath}" && git config user.name '${gitUsername}'`);
+      shellExec(`cd "${repoPath}" && git config user.email '${gitEmail}'`);
+
+      if (origin) {
+        const currentRemote = shellExec(`cd "${repoPath}" && git remote get-url origin 2>/dev/null || true`, {
+          stdout: true,
+          silent: true,
+        }).trim();
+        if (!currentRemote) {
+          shellExec(`cd "${repoPath}" && git remote add origin "${origin}"`);
+        } else if (currentRemote !== origin) {
+          shellExec(`cd "${repoPath}" && git remote set-url origin "${origin}"`);
+        }
+      }
+    },
+
+    manageBackupRepo({ repoName, operation, message = '', forceClone = false }) {
+      try {
+        const username = process.env.GITHUB_USERNAME;
+        if (!username) {
+          logger.error('GITHUB_USERNAME environment variable not set');
+          return false;
+        }
+
+        const repoPath = `../${repoName}`;
+
+        switch (operation) {
+          case 'clone':
+            if (forceClone && fs.existsSync(repoPath)) {
+              logger.info(`Force clone: removing existing repository: ${repoName}`);
+              fs.removeSync(repoPath);
+            }
+            if (!fs.existsSync(repoPath)) {
+              shellExec(`cd .. && underpost clone ${username}/${repoName}`);
+              logger.info(`Cloned repository: ${repoName}`);
+            }
+            break;
+
+          case 'pull':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && git checkout . && git clean -f -d`);
+              shellExec(`cd ${repoPath} && underpost pull . ${username}/${repoName}`, { silent: true });
+              logger.info(`Pulled repository: ${repoName}`);
+            }
+            break;
+
+          case 'commit':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && git add .`);
+              shellExec(`underpost cmt ${repoPath} backup '' '${message}'`);
+              logger.info(`Committed to repository: ${repoName}`, { message });
+            }
+            break;
+
+          case 'push':
+            if (fs.existsSync(repoPath)) {
+              shellExec(`cd ${repoPath} && underpost push . ${username}/${repoName}`, { silent: true });
+              logger.info(`Pushed repository: ${repoName}`);
+            }
+            break;
+
+          default:
+            logger.warn(`Unknown git operation: ${operation}`);
+            return false;
+        }
+
+        return true;
+      } catch (error) {
+        logger.error(`Git operation failed`, { repoName, operation, error: error.message });
+        return false;
+      }
+    },
+
+    /**
+     * Runtime-type → in-pod site-root directory resolver.
+     * Maps each known runtime to the filesystem path where its repository lives inside the container.
+     * @param {string} runtime - The runtime identifier (e.g. 'wp').
+     * @param {string} host - The virtual-host name.
+     * @returns {string|null} Absolute path inside the pod, or null if the runtime has no known mapping.
+     * @memberof UnderpostRepository
+     */
+    runtimeSiteRoot(runtime, host) {
+      const runtimePaths = {
+        wp: `/opt/lampp/htdocs/wp/${host}`,
+      };
+      return runtimePaths[runtime] || null;
+    },
+
+    /**
+     * Backs up all repositories defined in a deployment's conf.server.json by executing
+     * git commit+push inside the running deployment pod via `kubectl exec`.
+     *
+     * Scans every `server[host][path]` entry for a `repository` field. For each match
+     * the runtime-specific site root is resolved and a git backup script is executed
+     * inside the pod. GITHUB_TOKEN and GITHUB_USERNAME are injected as ephemeral
+     * environment variables in the exec command — never persisted to the pod filesystem.
+     *
+     * @param {object} opts
+     * @param {string}  opts.deployId   - Deployment ID (used to read conf.server.json and find pods).
+     * @param {string}  [opts.namespace='default'] - Kubernetes namespace.
+     * @param {string}  [opts.env='production'] - Deployment environment.
+     * @returns {void}
+     * @memberof UnderpostRepository
+     */
+    backupPodRepositories({ deployId, namespace = 'default', env = 'production' }) {
+      const confServer = readConfJson(deployId, 'server', { resolve: true });
+      const githubToken = process.env.GITHUB_TOKEN || '';
+      const githubUsername = process.env.GITHUB_USERNAME || 'underpostnet';
+
+      if (!githubToken) {
+        logger.warn('backupPodRepositories: GITHUB_TOKEN not available — git push will fail');
+      }
+
+      // Resolve the active blue/green traffic colour so we target the correct pod
+      const traffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace });
+      if (!traffic) {
+        logger.warn(`backupPodRepositories: could not resolve current traffic for ${deployId} — skipping`);
+        return;
+      }
+
+      // Find a running pod that matches the active traffic colour
+      const pods = Underpost.kubectl.get(`${deployId}-${env}-${traffic}`, 'pods', namespace);
+      const runningPod = pods.find((p) => p.STATUS === 'Running');
+      if (!runningPod) {
+        logger.warn(`backupPodRepositories: no running ${traffic} pod found for ${deployId} in namespace ${namespace}`);
+        return;
+      }
+      const podName = runningPod.NAME;
+
+      for (const host of Object.keys(confServer)) {
+        for (const routePath of Object.keys(confServer[host])) {
+          const entry = confServer[host][routePath];
+          if (!entry.repository) continue;
+
+          const siteRoot = Underpost.repo.runtimeSiteRoot(entry.runtime, host);
+          if (!siteRoot) {
+            logger.warn(`backupPodRepositories: no site-root mapping for runtime '${entry.runtime}' (${host})`);
+            continue;
+          }
+
+          const repoName = entry.repository.split('/').pop().split('.')[0];
+
+          // Build the backup script — secrets are injected as env vars in the exec,
+          // never written to filesystem. The shell process inherits them ephemerally.
+          const backupScript = [
+            `export GITHUB_TOKEN='${githubToken.replace(/'/g, "'\\''")}'`,
+            `export GITHUB_USERNAME='${githubUsername.replace(/'/g, "'\\''")}'`,
+            `git config --global --add safe.directory '${siteRoot}' 2>/dev/null || true`,
+            `cd '${siteRoot}' && git add -A && git commit -m 'backup $(date -u +%Y-%m-%dT%H:%M:%SZ)' || true`,
+            `cd '${siteRoot}' && underpost push . ${githubUsername}/${repoName}`,
+            `cd /home/dd/engine && node bin secret underpost --global-clean`,
+          ].join(' && ');
+
+          try {
+            logger.info(`backupPodRepositories: backing up ${host} (${entry.runtime}) in pod ${podName}`);
+            Underpost.kubectl.exec({ podName, namespace, command: backupScript });
+            logger.info(`backupPodRepositories: git push done for ${host}`);
+          } catch (err) {
+            logger.error(`backupPodRepositories: backup failed for ${host}`, err.message);
+          }
+        }
+      }
+    },
+
+    /**
+     * Clones the deploy-specific private repository into `./engine-private`
+     * when it does not already exist on disk.  Returns `{ ephemeral: true }`
+     * If `./engine-private` already exists, the call is a no-op unless
+     * `options.force` is `true`, in which case the directory is removed and
+     * re-cloned.
+     *
+     * @param {string} [deployId] - Deploy ID (e.g. `dd-core`) used to derive
+     *        the repo name `engine-{component}-private`.  Falls back to
+     *        `process.env.DEFAULT_DEPLOY_ID`.  When neither is available the
+     *        default repo name `engine-private` is used.
+     * @param {object} [options]
+     * @param {boolean} [options.force=false] - Remove existing `engine-private`
+     *        and re-clone.
+     * @memberof UnderpostRepository
+     */
+    privateEngineRepoFactory(deployId, options = { force: false }) {
+      if (fs.existsSync('./engine-private') && !options.force) return;
+
+      if (options.force && fs.existsSync('./engine-private')) {
+        fs.removeSync('./engine-private');
+        logger.info('engine-private removed (force re-clone)');
+      }
+
+      const effectiveDeployId = deployId || process.env.DEFAULT_DEPLOY_ID;
+
+      const username = process.env.GITHUB_USERNAME;
+      if (!username) {
+        throw new Error('privateEngineRepoFactory: GITHUB_USERNAME not set');
+      }
+
+      const repoName = effectiveDeployId ? `engine-${effectiveDeployId.split('-')[1]}-private` : 'engine-private';
+      logger.info(`engine-private missing — cloning ${username}/${repoName}`);
+      shellExec(`underpost clone ${username}/${repoName}`);
+      if (!fs.existsSync(`./${repoName}`)) {
+        throw new Error(`privateEngineRepoFactory: clone failed for ${username}/${repoName}`);
+      }
+      if (repoName !== 'engine-private') shellExec(`mv ./${repoName} ./engine-private`);
+    },
+
+    /**
+     * Removes the ephemeral `engine-private/` clone created by
+     * `privateEngineRepoFactory()`.  No-op if the directory does not exist.
+     * @memberof UnderpostRepository
+     */
+    cleanupPrivateEngineRepo() {
+      if (fs.existsSync('./engine-private')) {
+        fs.removeSync('./engine-private');
+        logger.info('engine-private ephemeral clone removed');
+      }
+      if (fs.existsSync('/home/dd/engine-private')) {
+        fs.removeSync('/home/dd/engine-private');
+        logger.info('engine-private in /home/dd removed');
+      }
+    },
   };
 }