cyberia 3.1.3 → 3.2.9

package/src/cli/repository.js

@@ -21,7 +21,7 @@ import {
   buildReplicaId,
   writeEnv,
 } from '../server/conf.js';
-import { buildClient } from '../server/client-build.js';
+import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../server/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
@@ -97,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.
@@ -127,11 +128,51 @@ 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,
@@ -304,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,
@@ -323,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,
@@ -352,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
      */
@@ -547,14 +597,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);
@@ -573,7 +618,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`);
@@ -597,6 +643,9 @@ class UnderpostRepository {
      * @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 {string|number} [options.split=''] - Optional ZIP part size in MB. When set with buildZip, writes split parts.
+     * @param {string} [options.unzip=''] - Optional build ZIP prefix to extract from ./build.
+     * @param {string} [options.mergeZip=''] - Optional build prefix to merge split ZIP parts into a single ZIP.
      * @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.
@@ -611,71 +660,32 @@ class UnderpostRepository {
         syncEnvPort: false,
         singleReplica: false,
         buildZip: false,
+        split: '',
+        unzip: '',
+        mergeZip: '',
         liteBuild: false,
         iconsBuild: false,
       },
     ) {
       return new Promise(async (resolve, reject) => {
         try {
-          // 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;
-
-              for (const envInstanceObj of dataEnv) {
-                const envPath = `${baseConfPath}/${deployId}/.env.${envInstanceObj.env}`;
-                const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
-                envObj.PORT = `${envInstanceObj.port + effectivePortOffset}`;
-                writeEnv(envPath, envObj);
-              }
-
-              if (singleReplicaPortOffsets[deployId] !== undefined) continue;
+          if (options.mergeZip) {
+            mergeClientBuildZip({
+              buildPrefix: options.mergeZip,
+              logger,
+            });
+            return resolve(true);
+          }
 
-              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++;
-                  }
-                }
-              }
-            }
+          if (options.unzip) {
+            unzipClientBuild({
+              buildPrefix: options.unzip,
+              logger,
+            });
             return resolve(true);
           }
 
-          // Handle singleReplica operation
+          // Handle singleReplica operation (must run before syncEnvPort to ensure replica dirs exist)
           if (options.singleReplica) {
             const replicaPath = path;
             if (!deployId || !host || !replicaPath) {
@@ -741,6 +751,71 @@ class UnderpostRepository {
                 }
               }
             }
+            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);
           }
 
@@ -752,6 +827,9 @@ class UnderpostRepository {
             let argPath = path ? path.split(',') : [];
             let deployIdSingleReplicas = [];
             let singleReplicaHosts = [];
+            const isReplicaContext = resolvedDeployId
+              ? fs.existsSync(`./engine-private/replica/${resolvedDeployId}`)
+              : false;
             const serverConf = resolvedDeployId
               ? readConfJson(resolvedDeployId, 'server', { loadReplicas: true })
               : Config.default.server;
@@ -762,7 +840,7 @@ class UnderpostRepository {
                 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) {
+                  if (!isReplicaContext && serverConf[host][path].singleReplica && serverConf[host][path].replicas) {
                     singleReplicaHosts.push({ host, path });
                     deployIdSingleReplicas = deployIdSingleReplicas.concat(
                       serverConf[host][path].replicas.map((replica) =>
@@ -775,10 +853,17 @@ class UnderpostRepository {
             }
             await buildClient({
               buildZip: options.buildZip || false,
+              split: options.split || '',
               fullBuild: options.liteBuild ? false : true,
               iconsBuild: options.iconsBuild || false,
             });
-            for (const replicaDeployId of deployIdSingleReplicas) await Underpost.repo.client(replicaDeployId);
+            for (const replicaDeployId of deployIdSingleReplicas) {
+              if (!fs.existsSync(`./engine-private/replica/${replicaDeployId}`)) {
+                logger.warn('Skip replica client build: replica folder not found', { replicaDeployId });
+                continue;
+              }
+              await Underpost.repo.client(replicaDeployId);
+            }
 
             return resolve(true);
           }
@@ -865,11 +950,12 @@ 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
      */
-    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,
@@ -884,7 +970,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,
@@ -1185,6 +1271,74 @@ Prevent build private config repo.`,
       logger.info('Dispatched workflow', `${repo} -> ${workflowFile}`, inputs.job ? `(job: ${inputs.job})` : '');
     },
 
+    /**
+     * 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) {
+      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;
+    },
+    /**
+     * 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
+     */
+    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);
+    },
+
+    /**
+     * 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,
+        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.
@@ -1207,6 +1361,253 @@ Prevent build private config repo.`,
         .trim()
         .replaceAll('] - ', '] ');
     },
+    /**
+     * 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}"`);
+        }
+      }
+    },
+    /**
+     * 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;
+        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');
+      }
+    },
   };
 }