@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/cli/repository.js

@@ -5,24 +5,16 @@
  */
 
 import dotenv from 'dotenv';
+import { execFileSync } from 'node:child_process';
 import { commitData } from '../client/components/core/CommonJs.js';
-import { pbcopy, shellCd, shellExec } from '../server/process.js';
-import { actionInitLog, loggerFactory } from '../server/logger.js';
+import { pbcopy, shellArgumentFactory, shellCd, shellExec } from '../server/runtime/process.js';
+import { actionInitLog, loggerFactory, redactSensitiveText } from '../server/ops/logger.js';
 import path from 'path';
 import fs from 'fs-extra';
-import {
-  Config,
-  loadConf,
-  readConfJson,
-  getConfFilePath,
-  loadReplicas,
-  loadConfServerJson,
-  getDataDeploy,
-  buildReplicaId,
-  readConfInstances,
-} from '../server/conf.js';
-import { getNpmRootPath, writeEnv } from '../server/environment.js';
-import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../client-builder/client-build.js';
+import { Config, readConfJson, readConfInstances } from '../server/runtime/conf.js';
+import { readDeployRoutes, registerDeployRoute } from '../server/network/router.js';
+import { getUnderpostRootPath } from '../server/runtime/environment.js';
+import { githubCommitUrlFactory, repositoryIdentityFactory } from '../server/storage/repository.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
@@ -50,18 +42,25 @@ class UnderpostRepository {
     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(
-        `git clone ${options?.bare === true ? ` --bare ` : ''}https://${
-          process.env.GITHUB_TOKEN ? `${process.env.GITHUB_TOKEN}@` : ''
-        }github.com/${gitUri}${gExtension}`,
-        {
-          disableLog: true,
-        },
-      );
+      const auth = Underpost.repo.gitAuthFactory(`https://github.com/${gitUri}${gExtension}`);
+      // A bare clone lands in `<repo>.git`: clearing `<repo>` instead would both leave the
+      // real target in place and delete an unrelated work tree that happens to share the name.
+      const clonePath = `./${repoName}${options?.bare === true ? gExtension : ''}`;
+      if (fs.existsSync(clonePath)) fs.removeSync(clonePath);
+      shellExec(`git clone ${options?.bare === true ? ` --bare ` : ''}"${auth.url}"`, {
+        disableLog: true,
+        env: auth.env,
+      });
     },
     /**
      * Pulls updates from a GitHub repository.
+     *
+     * `--ff-only` because the reconcile strategy must not come from the host: without it git
+     * refuses a divergent pull outright on a node that configured neither `pull.rebase` nor
+     * `pull.ff`, and silently merges or rebases on one that did — the same command producing a
+     * different history per machine. Advancing to the remote is what every caller wants; a
+     * checkout that has drifted onto commits of its own is replaced through
+     * {@link UnderpostRepository.switchRemote}, not reconciled here.
      * @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.
@@ -74,14 +73,11 @@ class UnderpostRepository {
       options = { g8: false },
     ) {
       const gExtension = options.g8 === true ? '.g8' : '.git';
-      shellExec(
-        `cd ${repoPath} && git pull https://${
-          process.env.GITHUB_TOKEN ? `${process.env.GITHUB_TOKEN}@` : ''
-        }github.com/${gitUri}${gExtension}`,
-        {
-          disableLog: true,
-        },
-      );
+      const auth = Underpost.repo.gitAuthFactory(`https://github.com/${gitUri}${gExtension}`);
+      shellExec(`cd ${repoPath} && git pull --ff-only "${auth.url}"`, {
+        disableLog: true,
+        env: auth.env,
+      });
     },
     /**
      * Creates a Git commit with a conventional commit message.
@@ -103,7 +99,7 @@ class UnderpostRepository {
      * @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.
      * @param {boolean|string} [options.changelog=undefined] - If true, prints the changelog since the last CI integration commit (starting with 'ci(package-pwa-microservices-'). If a number string, prints the changelog of the last N commits split by version sections. Only considers commits starting with '[<tag>]'.
-     * @param {boolean} [options.changelogBuild=false] - If true, scrapes all git history and builds a full CHANGELOG.md. Commits containing 'New release v:' are used as version section titles. Only commits starting with '[<tag>]' are included as entries.
+     * @param {boolean} [options.changelogBuild=false] - If true, scrapes git history and builds a CHANGELOG.md from the five latest versions. Commits containing 'New release v:' are used as version section titles. Only commits starting with '[<tag>]' are included as entries.
      * @param {string} [options.changelogMinVersion=''] - If set, overrides the default minimum version limit (2.85.0) for --changelog-build.
      * @param {boolean} [options.changelogNoHash=false] - If true, omits commit hashes from the changelog entries.
      * @param {boolean} [options.remoteUrl=false] - If true, prints the current git remote URL (origin) in plain text and returns.
@@ -226,6 +222,19 @@ class UnderpostRepository {
         return;
       }
 
+      if (options.propagateMsg) {
+        // Chain hop: carry the payload the previous workflow sent instead of regenerating it, so
+        // every repository downstream of the dispatch commits the same entries.
+        const propagated = Underpost.repo.resolvePropagationMessage(process.env.PROPAGATED_MESSAGE);
+        if (propagated) {
+          console.log(propagated);
+          return;
+        }
+        // Nothing arrived — fall through to this repository's own changelog for the last N commits.
+        options.changelogMsg = true;
+        options.changelogNoHash = true;
+      }
+
       if (options.changelog !== undefined || options.changelogBuild || options.changelogMsg !== undefined) {
         const releaseMatch = 'New release v:';
         // Helper: parse [<tag>] commits into grouped sections
@@ -279,9 +288,7 @@ class UnderpostRepository {
             .filter((c) => c.hash);
         };
 
-        const githubUser = process.env.GITHUB_USERNAME || 'underpostnet';
-        const commitUrl = (shortHash, fullHash) =>
-          `[${shortHash}](https://github.com/${githubUser}/engine/commit/${fullHash})`;
+        const commitUrl = (shortHash, hash) => githubCommitUrlFactory({ shortHash, hash });
 
         // Helper: extract version from commit message containing 'New release v:'
         const extractVersion = (message) => {
@@ -331,17 +338,19 @@ class UnderpostRepository {
         const changelogMinVersion = options.changelogMinVersion || '2.97.1';
 
         if (options.changelogBuild) {
-          // --changelog-build: scrape ALL history, split by 'New release v:' commits as version sections
+          // --changelog-build: retain the current changes and the five latest version sections.
           const allCommits = fetchHistory();
           const sections = buildVersionSections(allCommits);
 
-          // Filter sections: stop at changelogMinVersion boundary
+          // Stop at either the fifth release section or the configured minimum-version boundary.
           const limitedSections = [];
+          let versionCount = 0;
           for (const section of sections) {
             limitedSections.push(section);
             if (section.title) {
+              versionCount++;
               const versionStr = section.title.replace(releaseMatch, '').trim();
-              if (versionStr === changelogMinVersion) break;
+              if (versionCount === 5 || versionStr === changelogMinVersion) break;
             }
           }
 
@@ -441,7 +450,10 @@ class UnderpostRepository {
       } ${message ? message : commitData[commitType].description}`;
       if (options.copy) return pbcopy(_message);
       shellExec(
-        `cd ${repoPath} && git commit ${options?.empty ? `--allow-empty ` : ''}${options.edit ? `--amend  --no-edit ` : `-m "${_message}"`}`,
+        `cd ${repoPath} && git commit ${options?.empty ? `--allow-empty ` : ''}${
+          // A propagated payload is multi-line and may hold `$`: quoting keeps every entry intact.
+          options.edit ? `--amend  --no-edit ` : `-m ${shellArgumentFactory(_message)}`
+        }`,
       );
     },
 
@@ -474,14 +486,11 @@ class UnderpostRepository {
       options = { f: false, g8: false },
     ) {
       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' : ''
-        }`,
-        {
-          disableLog: true,
-        },
-      );
+      const auth = Underpost.repo.gitAuthFactory(`https://github.com/${gitUri}${gExtension}`);
+      shellExec(`cd ${repoPath} && git push "${auth.url}"${options?.f === true ? ' --force' : ''}`, {
+        disableLog: true,
+        env: auth.env,
+      });
       logger.info(
         'commit url',
         `http://github.com/${gitUri}${gExtension === '.g8' ? '.g8' : ''}/commit/${shellExec(
@@ -493,13 +502,96 @@ class UnderpostRepository {
       );
     },
 
+    /**
+     * Initializes the base cluster deploy folder `engine-private/deploy` from `./conf.js` (DefaultConf).
+     *
+     * Writes the minimum set required by the cluster runtime:
+     * `conf.event.json`, `conf.users.json`, `conf.wireguard.json`, `dd.cron`, `dd.routes`, `id_rsa`, `id_rsa.pub`.
+     *
+     * When a deploy ID is explicitly provided, it also generates the deploy CI/CD workflows and its default conf.
+     *
+     * Idempotent: existing files are never overwritten, so it is safe to rerun over a provisioned cluster.
+     * @param {string} [deployId=''] - Deploy ID registered in the route table and used as default cron deploy ID (defaults to `dd-default`, `dd-` prefix is normalized).
+     * @returns {{ deployPath: string, created: string[] }} The deploy folder and the files created by this run.
+     * @memberof UnderpostRepository
+     */
+    clusterDeployFactory(deployId = '') {
+      const deployPath = './engine-private/deploy';
+      const created = [];
+
+      const hasDeployId = `${deployId || ''}`.trim().length > 0;
+      deployId = `${deployId || ''}`.trim() || 'dd-default';
+      if (!deployId.startsWith('dd-')) deployId = `dd-${deployId}`;
+
+      fs.mkdirSync(deployPath, { recursive: true });
+
+      const confFiles = {
+        'conf.event.json': DefaultConf.event,
+        'conf.users.json': DefaultConf.users,
+        'conf.wireguard.json': DefaultConf.wireguard,
+      };
+
+      for (const [fileName, conf] of Object.entries(confFiles)) {
+        const confPath = `${deployPath}/${fileName}`;
+        if (fs.existsSync(confPath)) continue;
+        fs.writeFileSync(confPath, JSON.stringify(conf, null, 4), 'utf8');
+        created.push(confPath);
+      }
+
+      const cronPath = `${deployPath}/dd.cron`;
+      if (!fs.existsSync(cronPath)) {
+        fs.writeFileSync(cronPath, deployId, 'utf8');
+        created.push(cronPath);
+      }
+
+      const routesPath = `${deployPath}/dd.routes`;
+      const routesExists = fs.existsSync(routesPath);
+      registerDeployRoute(deployId);
+      if (!routesExists) created.push(routesPath);
+
+      const keyPath = `${deployPath}/id_rsa`;
+      const pubKeyPath = `${deployPath}/id_rsa.pub`;
+      if (!fs.existsSync(keyPath)) {
+        shellExec(`ssh-keygen -t ed25519 -f ${keyPath} -N "" -q -C "root@${deployId}"`, { disableLog: true });
+        fs.chmodSync(keyPath, 0o600);
+        created.push(keyPath);
+        created.push(pubKeyPath);
+      } else if (!fs.existsSync(pubKeyPath)) {
+        shellExec(`ssh-keygen -y -f ${keyPath} -P "" > ${pubKeyPath}`, { disableLog: true });
+        created.push(pubKeyPath);
+      }
+
+      if (hasDeployId) {
+        const repoName = `engine-${deployId.split('dd-')[1]}`;
+        fs.writeFileSync(
+          `./.github/workflows/${repoName}.cd.yml`,
+          fs
+            .readFileSync(`./.github/workflows/engine-test.cd.yml`, 'utf8')
+            .replaceAll('test', deployId.split('dd-')[1]),
+          'utf8',
+        );
+        fs.writeFileSync(
+          `./.github/workflows/${repoName}.ci.yml`,
+          fs
+            .readFileSync(`./.github/workflows/engine-test.ci.yml`, 'utf8')
+            .replaceAll('test', deployId.split('dd-')[1]),
+          'utf8',
+        );
+        shellExec(`node bin new --default-conf --deploy-id ${deployId}`);
+      }
+
+      logger.info('Cluster deploy base', { deployPath, created });
+
+      return { deployPath, created };
+    },
+
     /**
      * Initializes a new Underpost repository, optionally setting up a deploy ID or sub-configuration.
      * @param {string} [projectName=''] - The name of the project to create.
      * @param {object} [options] - Initialization options.
      * @param {string} [options.deployId=''] - The deployment ID to set up.
      * @param {string} [options.subConf=''] - The sub-configuration to create.
-     * @param {boolean} [options.cluster=false] - If true, sets up a clustered configuration.
+     * @param {boolean} [options.cluster=false] - If true, initializes only the base cluster deploy folder (`engine-private/deploy`) from `./conf.js` and returns; no project or deploy ID scaffolding runs.
      * @param {boolean} [options.dev=false] - If true, uses development settings.
      * @param {boolean} [options.buildRepos=false] - If true, creates the deployment repositories (engine-*, engine-*-private, engine-*-cron-backups).
      * @param {boolean} [options.purge=false] - If true, removes the deploy ID conf and all related repositories (requires deployId).
@@ -534,6 +626,12 @@ class UnderpostRepository {
           await logger.setUpInfo();
           actionInitLog();
 
+          // Handle cluster deploy base operation (standalone: never scaffolds a project)
+          if (options.cluster === true) {
+            UnderpostRepository.API.clusterDeployFactory(options.deployId || projectName);
+            return resolve(true);
+          }
+
           // Handle cleanTemplate operation
           if (options.cleanTemplate) {
             logger.info('Cleaning build directory');
@@ -630,8 +728,6 @@ class UnderpostRepository {
               ];
 
               const username = process.env.GITHUB_USERNAME;
-              const token = process.env.GITHUB_TOKEN;
-
               if (!username) {
                 logger.error('GITHUB_USERNAME environment variable not set');
                 return reject(false);
@@ -643,7 +739,7 @@ class UnderpostRepository {
                   logger.info(`Created repository directory: ${repo.path}`);
                 }
 
-                const remoteUrl = `https://${token ? `${token}@` : ''}github.com/${username}/${repo.name}.git`;
+                const remoteUrl = `https://github.com/${username}/${repo.name}.git`;
                 UnderpostRepository.API.initLocalRepo({ path: repo.path, origin: remoteUrl });
                 logger.info(`Initialized git repository with remote: ${repo.name}`);
               }
@@ -674,257 +770,7 @@ class UnderpostRepository {
           }
           return resolve(true);
         } catch (error) {
-          console.log(error);
-          logger.error(error, error.stack);
-          return reject(false);
-        }
-      });
-    },
-
-    /**
-     * 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 {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.
-     * @memberof UnderpostRepository
-     */
-    client(
-      deployId = 'dd-default',
-      subConf = '',
-      host = '',
-      path = '',
-      options = {
-        syncEnvPort: false,
-        singleReplica: false,
-        buildZip: false,
-        split: '',
-        unzip: '',
-        mergeZip: '',
-        liteBuild: false,
-        iconsBuild: false,
-      },
-    ) {
-      return new Promise(async (resolve, reject) => {
-        try {
-          if (options.mergeZip) {
-            mergeClientBuildZip({
-              buildPrefix: options.mergeZip,
-              logger,
-            });
-            return resolve(true);
-          }
-
-          if (options.unzip) {
-            unzipClientBuild({
-              buildPrefix: options.unzip,
-              logger,
-            });
-            return resolve(true);
-          }
-
-          // 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 isReplicaContext = resolvedDeployId
-              ? fs.existsSync(`./engine-private/replica/${resolvedDeployId}`)
-              : false;
-            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 (!isReplicaContext && 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({
-              deployId: resolvedDeployId,
-              buildZip: options.buildZip || false,
-              split: options.split || '',
-              fullBuild: options.liteBuild ? false : true,
-              iconsBuild: options.iconsBuild || false,
-              ssrOnly: options.ssr || false,
-            });
-            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, '', '', '', {
-                buildZip: options.buildZip || false,
-                split: options.split || '',
-                liteBuild: options.liteBuild || false,
-                iconsBuild: options.iconsBuild || false,
-                ssr: options.ssr || false,
-              });
-            }
-
-            return resolve(true);
-          }
-        } catch (error) {
-          console.log(error);
+          console.error(error);
           logger.error(error, error.stack);
           return reject(false);
         }
@@ -943,6 +789,16 @@ class UnderpostRepository {
       return diffUntrackOutput.toString().split('\n').filter(Boolean);
     },
 
+    // Read tracked paths without changing the index or working tree.
+    getTrackedFiles(directory = '.') {
+      const options = { cwd: path.resolve(directory), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 };
+      const root = execFileSync('git', ['rev-parse', '--show-toplevel'], options).replace(/\r?\n$/, '');
+      return execFileSync('git', ['ls-files', '--cached', '--full-name', '-z', '--', '.'], options)
+        .split('\0')
+        .filter(Boolean)
+        .map((file) => path.resolve(root, file));
+    },
+
     /**
      * Gets a list of changed (modified and untracked) files in a Git repository.
      * @param {string} [path='.'] - The path to the repository.
@@ -973,7 +829,7 @@ class UnderpostRepository {
      */
     privateConfUpdate(deployId) {
       shellCd(`/home/dd/engine`);
-      const privateRepoName = `engine-${deployId.split('dd-')[1]}-private`;
+      const privateRepoName = Underpost.repo.privateRepoFactory(deployId);
       const privateRepoPath = `../${privateRepoName}`;
       if (fs.existsSync(privateRepoPath)) fs.removeSync(privateRepoPath);
       shellExec(`cd .. && underpost clone ${process.env.GITHUB_USERNAME}/${privateRepoName}`);
@@ -1274,23 +1130,32 @@ Prevent build private config repo.`,
     /**
      * Resolves the default branch for a remote GitHub repository by querying
      * `git ls-remote --symref` and extracting the HEAD ref target.
-     * Falls back to `main` when detection fails.
      * @param {string} repo - The GitHub repository (e.g., "owner/repo").
      * @returns {string} The default branch name (e.g. "main" or "master").
      * @memberof UnderpostRepository
      */
     getDefaultBranch(repo) {
-      if (!repo) return 'main';
-      const authUrl = Underpost.repo.resolveAuthUrl(repo);
-      const raw = shellExec(
-        `GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote --symref "${authUrl}" HEAD 2>&1`,
-        { stdout: true, silent: true, disableLog: true, silentOnError: true },
-      );
+      if (!repo) throw new Error('[repo] getDefaultBranch requires a repository reference');
+      const auth = Underpost.repo.gitAuthFactory(repo);
+      const raw = shellExec(`git ls-remote --symref "${auth.url}" HEAD 2>&1`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+        env: auth.env,
+      });
       // --symref emits a line like: ref: refs/heads/main	HEAD
       const match = typeof raw === 'string' ? raw.match(/^ref:\s*refs\/heads\/(\S+)\tHEAD$/m) : null;
-      const branch = match ? match[1] : 'main';
-      logger.info('getDefaultBranch', { repo, branch });
-      return branch;
+      // Guessing here is worse than failing: `main` against a `master` remote
+      // fetches a ref that does not exist, and the caller has already pointed
+      // origin at the new URL by the time git says so.
+      if (!match)
+        throw new Error(
+          `[repo] cannot read the default branch of '${repo}'; it may be empty, unreachable, ` +
+            `or need credentials: ${redactSensitiveText(`${raw || ''}`.trim().split('\n').pop() || 'no ref reported')}`,
+        );
+      logger.info('getDefaultBranch', { repo, branch: match[1] });
+      return match[1];
     },
 
     /**
@@ -1323,7 +1188,7 @@ Prevent build private config repo.`,
       } else {
         let token = process.env.GITHUB_TOKEN;
         if (!token) {
-          const envPath = `${getNpmRootPath()}/underpost/.env`;
+          const envPath = `${getUnderpostRootPath()}/.env`;
           if (fs.existsSync(envPath) && fs.statSync(envPath).isFile()) {
             const envVars = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
             token = envVars.GITHUB_TOKEN;
@@ -1348,46 +1213,220 @@ Prevent build private config repo.`,
     },
 
     /**
-     * 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.
+     * Normalizes a repository reference to a clone URL, expanding the short
+     * `owner/repo` form against GitHub.
+     * @param {string} url - Repository URL or `owner/repo` short form.
+     * @returns {string} Clone URL, unchanged when one was already given.
+     * @memberof UnderpostRepository
+     */
+    repoUrlFactory(url = '') {
+      const value = `${url || ''}`.trim();
+      if (!value) return value;
+      const remote = value.startsWith('http://') || value.startsWith('https://') || value.startsWith('git@');
+      return remote ? value : `https://github.com/${value}`;
+    },
+
+    /**
+     * Reduces a repository reference to its `owner/repo` slug, the form the
+     * clone and pull commands take.
+     * @param {string} url - Repository URL or `owner/repo` short form.
+     * @returns {string} Slug.
+     * @throws {Error} When no owner and repository can be read from the reference.
+     * @memberof UnderpostRepository
+     */
+    repoSlugFactory(url = '') {
+      const path = Underpost.repo
+        .repoUrlFactory(url)
+        .replace(/^git@[^:]+:/, '')
+        .replace(/^https?:\/\/[^/]+\//, '')
+        .replace(/\.git$/, '')
+        .replace(/\/+$/, '');
+      const [owner, repo] = path.split('/');
+      if (!owner || !repo) throw new Error(`[repo] '${url}' is not an owner/repo reference or a clone URL`);
+      return `${owner}/${repo}`;
+    },
+
+    /**
+     * Reduces any deploy-scoped reference to the conf id its repositories share.
+     *
+     * Single source of that parsing: deploy ids (`dd-lampp`), source repos (`engine-lampp`),
+     * test source repos (`engine-test-lampp`) and private conf repos (`engine-lampp-private`)
+     * all name the same deployment, and the monorepo (`engine` / `engine-private`) names none.
+     * @param {string} reference - Deploy id, repository name, `owner/repo` slug, or clone URL.
+     * @returns {string} Conf id, or `''` for the monorepo.
+     * @memberof UnderpostRepository
+     */
+    confIdFactory(reference = '') {
+      const name = `${reference || ''}`
+        .trim()
+        .split('/')
+        .pop()
+        .replace(/\.git$/, '');
+      const confId = name
+        .replace(/^dd-/, '')
+        .replace(/^engine-test-/, '')
+        .replace(/^engine-/, '')
+        .replace(/-private$/, '');
+      return confId === 'engine' || confId === 'private' ? '' : confId;
+    },
+
+    /**
+     * Names the engine source repository a reference deploys from.
+     * @param {string} reference - Deploy id or repository reference.
+     * @param {object} [options] - Naming options.
+     * @param {boolean} [options.test=false] - Name the private test source repo instead.
+     * @returns {string} Repository name, without owner.
+     * @memberof UnderpostRepository
+     */
+    engineRepoFactory(reference = '', options = { test: false }) {
+      const confId = Underpost.repo.confIdFactory(reference);
+      if (!confId) return 'engine';
+      return options?.test === true ? `engine-test-${confId}` : `engine-${confId}`;
+    },
+
+    /**
+     * Names the private configuration repository a reference's conf lives in.
+     * @param {string} reference - Deploy id or repository reference.
+     * @returns {string} Repository name, without owner.
+     * @memberof UnderpostRepository
+     */
+    privateRepoFactory(reference = '') {
+      const confId = Underpost.repo.confIdFactory(reference);
+      return confId ? `engine-${confId}-private` : 'engine-private';
+    },
+
+    /**
+     * Names the canonical GitHub package repository a reference's engine mirrors into.
+     *
+     * The monorepo has none — `.github/workflows/ghpkg.ci.yml` builds `engine-ghpkg-<conf_id>`
+     * per deploy, and the template lineage mirrors into `pwa-microservices-template-ghpkg`
+     * instead — so an unnamed deploy resolves to `''` rather than an invented name.
+     * @param {string} reference - Deploy id or repository reference.
+     * @returns {string} Repository name without owner, or `''` for the monorepo.
+     * @memberof UnderpostRepository
+     */
+    ghpkgRepoFactory(reference = '') {
+      const confId = Underpost.repo.confIdFactory(reference);
+      return confId ? `engine-ghpkg-${confId}` : '';
+    },
+
+    /**
+     * Every distinct repository a deploy's instances are built from, as declared by
+     * `metadata.repository` in its `conf.instances.json`.
+     *
+     * An instance is a separate product with its own repository and its own workflows —
+     * `dd-cyberia` builds from `cyberia-server` and `cyberia-client` — so anything acting on
+     * "the repositories of a deploy" has to include them or it covers only half the deploy.
+     * The path is left to {@link readConfInstances} rather than rebuilt here.
+     * @param {string} deployId - Deploy id (e.g. `dd-cyberia`).
+     * @returns {Array<string>} Deduplicated `owner/repo` slugs, empty when the deploy declares none.
      * @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}`;
+    instanceRepos(deployId = '') {
+      const id = `${deployId || ''}`.trim();
+      if (!id) return [];
+      try {
+        return [
+          ...new Set(
+            readConfInstances(id)
+              .map((entry) => entry?.metadata?.repository)
+              .filter(Boolean),
+          ),
+        ];
+      } catch (error) {
+        // A deploy that declares no instances has no file, which is not a fault; anything else is.
+        if (error.code !== 'ENOENT')
+          logger.warn(`[repo] unreadable conf.instances.json for ${id}`, { error: error.message });
+        return [];
       }
+    },
+
+    /**
+     * Resolves the repository pair a node checks out: the engine source and the private
+     * configuration that belongs to it.
+     *
+     * One source of that pairing, because two callers compose it — `run pull` on the node
+     * itself and `edge --sync` composing the same pull for a fleet — and a node whose engine
+     * and conf came from two different resolutions reads a conf that does not describe it.
+     * The private repository is derived from the conf id the two share and takes the engine's
+     * owner, so naming only the source can never split the pair: `underpostnet/engine-test-lampp`
+     * pairs with `underpostnet/engine-lampp-private`, as does `underpostnet/engine-lampp`.
+     * Naming `enginePrivate` overrides that derivation with its own `owner/repo` or clone URL.
+     * @param {object} [options] - Pair options.
+     * @param {string} [options.engine] - Engine source, as `owner/repo` or a clone URL.
+     * @param {string} [options.enginePrivate] - Private configuration repository, overriding the derivation.
+     * @param {string} [options.account] - Owner the monorepo defaults to; `GITHUB_USERNAME` otherwise.
+     * @returns {{engine: string, enginePrivate: string}} Both slugs.
+     * @memberof UnderpostRepository
+     */
+    enginePairFactory({ engine = '', enginePrivate = '', account = '' } = {}) {
+      const owner = `${account || ''}`.trim() || process.env.GITHUB_USERNAME || 'underpostnet';
+      const source = Underpost.repo.repoSlugFactory(`${engine || ''}`.trim() || `${owner}/engine`);
+      const conf = `${enginePrivate || ''}`.trim();
+      return {
+        engine: source,
+        enginePrivate: conf
+          ? Underpost.repo.repoSlugFactory(conf)
+          : `${source.split('/')[0]}/${Underpost.repo.privateRepoFactory(source)}`,
+      };
+    },
+
+    /**
+     * Fast-forwards the engine and engine-private checkouts ahead of a template deploy.
+     *
+     * The deploy runners publish local commits, so they must not take the `run pull` route: that one
+     * is for provisioning a node and force-replaces both trees at the remote tip, discarding the very
+     * commits being published. `underpost pull` is `git pull --ff-only`, so a diverged checkout stops
+     * the deploy instead of losing history.
+     * @param {string} baseCommand - Resolved `underpost` CLI invocation.
+     * @returns {void}
+     */
+    fastForwardEnginePair(baseCommand) {
+      shellExec(`${baseCommand} pull . ${process.env.GITHUB_USERNAME}/engine`);
+      shellExec(`${baseCommand} pull ./engine-private ${process.env.GITHUB_USERNAME}/engine-private`);
+    },
+
+    /**
+     * Keeps GitHub credentials in the child environment instead of command arguments or remotes.
+     * @param {string} url - Repository URL or owner/repo reference.
+     * @returns {{url: string, env: NodeJS.ProcessEnv}} Token-free URL and Git child environment.
+     * @memberof UnderpostRepository
+     */
+    gitAuthFactory(url) {
+      const normalized = Underpost.repo.repoUrlFactory(url).replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/i, '$1');
+      const env = {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'credential.helper',
+        GIT_CONFIG_VALUE_0: '',
+      };
       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/`,
-        );
+        env.GIT_CONFIG_COUNT = '2';
+        env.GIT_CONFIG_KEY_1 = 'http.https://github.com/.extraheader';
+        env.GIT_CONFIG_VALUE_1 = `AUTHORIZATION: basic ${Buffer.from(
+          `x-access-token:${process.env.GITHUB_TOKEN}`,
+        ).toString('base64')}`;
       }
-      return normalized;
+      return { url: normalized, env };
     },
     /**
      * 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.
+     * Passes `GITHUB_TOKEN` to Git through its child environment 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.
-      // `-c credential.helper=` disables any host-configured credential helper so its stderr
-      // warnings don't pollute the ls-remote output; the token is already embedded in authUrl.
-      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote "${authUrl}" HEAD 2>&1`, {
+      const auth = Underpost.repo.gitAuthFactory(url);
+      const raw = shellExec(`git ls-remote "${auth.url}" HEAD 2>&1`, {
         stdout: true,
         silent: true,
         disableLog: true,
         silentOnError: true,
+        env: auth.env,
       });
       const refLine = typeof raw === 'string' ? (raw.match(/^[0-9a-f]{40}\t.*$/m) || [])[0] : undefined;
       const accessible = !!refLine;
@@ -1420,7 +1459,7 @@ Prevent build private config repo.`,
      * Sequence (idempotent, re-runnable):
      *   1. Normalize the URL (`owner/repo` → full GitHub HTTPS) and set/add the
      *      remote, storing the token-free URL so no secret leaks into `.git/config`.
-     *   2. Force-fetch the target branch (auth injected inline for private repos).
+     *   2. Force-fetch the target branch with credentials isolated in the child environment.
      *   3. Reset the working tree to the fetched tip and check out the target
      *      branch, overwriting any current tracked content.
      *
@@ -1438,23 +1477,58 @@ Prevent build private config repo.`,
       if (!url) throw new Error('switchRemote requires a target remote url');
       if (!fs.existsSync(`${repoPath}/.git`)) throw new Error(`switchRemote: not a git repository: ${repoPath}`);
       const targetBranch = branch || Underpost.repo.getDefaultBranch(url);
-      // Token-free URL for the stored remote; auth-injected URL only for the fetch.
-      let normalized = url;
-      if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('git@')) {
-        normalized = `https://github.com/${url}`;
-      }
-      const authUrl = Underpost.repo.resolveAuthUrl(url);
+      const auth = Underpost.repo.gitAuthFactory(url);
       const current = Underpost.repo.getRemoteUrl({ path: repoPath, remote });
-      if (!current) shellExec(`cd "${repoPath}" && git remote add ${remote} "${normalized}"`);
-      else shellExec(`cd "${repoPath}" && git remote set-url ${remote} "${normalized}"`);
-      logger.info('switchRemote', { path: repoPath, remote, branch: targetBranch, url: normalized });
-      shellExec(`cd "${repoPath}" && GIT_TERMINAL_PROMPT=0 git fetch --force "${authUrl}" ${targetBranch}`);
+      if (!current) shellExec(`cd "${repoPath}" && git remote add ${remote} "${auth.url}"`);
+      else shellExec(`cd "${repoPath}" && git remote set-url ${remote} "${auth.url}"`);
+      logger.info('switchRemote', { path: repoPath, remote, branch: targetBranch, url: auth.url });
+      shellExec(`cd "${repoPath}" && git fetch --force "${auth.url}" ${targetBranch}`, { env: auth.env });
       // reset --hard first clears the worktree so the checkout cannot be blocked
       // by conflicting local changes; -B points the target branch at the fetched tip.
       shellExec(`cd "${repoPath}" && git reset --hard FETCH_HEAD`);
       shellExec(`cd "${repoPath}" && git checkout -B ${targetBranch} FETCH_HEAD`);
     },
 
+    /**
+     * Brings a local checkout to the requested repository at its tip, whatever state it is in.
+     *
+     * Clones when the path is absent, and otherwise replaces the checkout through
+     * {@link UnderpostRepository.switchRemote} — the same operation `underpost cmt --switch-repo`
+     * runs, so a node reached by `run pull` and a node reached by `edge --sync` end on the same
+     * commit by the same route.
+     *
+     * One operation covers both the retarget and the same-repository case, because they only
+     * look different: an `--ff-only` pull refuses a checkout that has drifted onto commits of
+     * its own, which is exactly the node that most needs bringing back. A deploy checkout is a
+     * projection of its remote, never a place work is authored, so it is replaced rather than
+     * reconciled.
+     *
+     * The clone lands under the repository's own name and is renamed into place, because the
+     * checkout path is fixed by the deployment layout while the repository name is not.
+     *
+     * @param {object} opts
+     * @param {string} opts.path - Absolute checkout path.
+     * @param {string} opts.repo - Repository `owner/repo` slug or clone URL.
+     * @param {string} [opts.branch] - Branch to land on; the remote's default branch otherwise.
+     * @returns {'cloned'|'switched'} What the call had to do.
+     * @memberof UnderpostRepository
+     */
+    syncCheckout({ path: checkoutPath, repo, branch = '' }) {
+      const slug = Underpost.repo.repoSlugFactory(repo);
+      const repoName = slug.split('/')[1];
+      const parent = path.dirname(checkoutPath);
+
+      if (!fs.existsSync(checkoutPath)) {
+        fs.mkdirSync(parent, { recursive: true });
+        shellExec(`cd ${parent} && underpost clone ${slug}`, { silent: true });
+        if (`${parent}/${repoName}` !== checkoutPath) shellExec(`sudo mv ${parent}/${repoName} ${checkoutPath}`);
+        return 'cloned';
+      }
+
+      Underpost.repo.switchRemote({ url: slug, path: checkoutPath, branch });
+      return 'switched';
+    },
+
     /**
      * Returns metadata about unpushed commits in a git repository.
      * Fetches from origin, then counts commits ahead of the remote branch.
@@ -1519,6 +1593,41 @@ Prevent build private config repo.`,
       // callers fall back to their own generic default.
       return sanitized === 'No changelog entries found.' ? '' : sanitized;
     },
+    /**
+     * Resolves the changelog payload a workflow received from the previous link of the
+     * propagation chain.
+     *
+     * Every hop commits the payload with `cmt`, which wraps it as
+     * `type(scope): <emoji> <first entry>` — the newest entry rides on the subject line, so a
+     * downstream hop that drops the whole subject line loses it. This strips only the wrapper
+     * and keeps every entry, on its own line, in order.
+     *
+     * @param {string} rawMessage - The message as received (a commit message or a dispatch input).
+     * @returns {string} The propagated entries, or an empty string when there is nothing to carry.
+     * @memberof UnderpostRepository
+     */
+    resolvePropagationMessage(rawMessage) {
+      if (!rawMessage) return '';
+      const types = Object.keys(commitData).join('|');
+      const emojis = Object.values(commitData)
+        .map(({ emoji }) => emoji)
+        .filter(Boolean);
+      const lines = `${rawMessage}`
+        .replace(new RegExp(`^(${types})(\\([^)]*\\))?:\\s*`), '')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+      if (lines[0]) {
+        for (const emoji of emojis)
+          if (lines[0].startsWith(emoji)) {
+            lines[0] = lines[0].slice(emoji.length).trim();
+            break;
+          }
+        if (!lines[0]) lines.shift();
+      }
+      return lines.join('\n');
+    },
+
     /**
      * Initializes a git repository at the given path and configures user identity
      * from environment variables (`GITHUB_USERNAME` / `GITHUB_EMAIL`).
@@ -1530,9 +1639,13 @@ Prevent build private config repo.`,
      * @memberof UnderpostRepository
      */
     initLocalRepo({ path: repoPath, origin }) {
-      const gitUsername = process.env.GITHUB_USERNAME || 'underpostnet';
+      const gitUsername = repositoryIdentityFactory().owner;
       const gitEmail = process.env.GITHUB_EMAIL || `development@underpost.net`;
 
+      // Runtime document roots are chowned to the web server user, and git refuses to operate on
+      // a tree owned by someone else until it is declared safe.
+      Underpost.repo.declareSafeDirectory(repoPath);
+
       if (!fs.existsSync(`${repoPath}/.git`)) {
         shellExec(`mkdir -p "${repoPath}" && git init "${repoPath}"`);
       }
@@ -1598,6 +1711,18 @@ Prevent build private config repo.`,
           case 'commit':
             if (fs.existsSync(repoPath)) {
               shellExec(`cd ${repoPath} && git add .`);
+              // A backup run that produced no new bytes is a normal outcome, not a
+              // failure: committing anyway exits non-zero and buries real errors.
+              const pending = shellExec(`cd ${repoPath} && git status --porcelain`, {
+                stdout: true,
+                silent: true,
+                disableLog: true,
+                silentOnError: true,
+              });
+              if (!`${pending || ''}`.trim()) {
+                logger.info(`No changes to commit: ${repoName}`, { message });
+                break;
+              }
               shellExec(`underpost cmt ${repoPath} backup '' '${message}'`);
               logger.info(`Committed to repository: ${repoName}`, { message });
             }
@@ -1622,6 +1747,108 @@ Prevent build private config repo.`,
       }
     },
 
+    /**
+     * Reports whether a path already sits inside a git work tree, so callers can skip
+     * initializing a repository that would nest inside an existing one.
+     * @param {string} repoPath - Directory to probe.
+     * @returns {boolean} True when the path is tracked by an enclosing repository.
+     * @memberof UnderpostRepository
+     */
+    isInsideWorkTree(repoPath) {
+      const output = shellExec(`cd "${repoPath}" && git rev-parse --is-inside-work-tree`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      });
+      return `${output ?? ''}`.trim() === 'true';
+    },
+
+    /**
+     * Declares a path safe for git, skipping the write when it is already declared so repeated
+     * provisioning does not append duplicate global config entries.
+     * @param {string} repoPath - Absolute path to declare.
+     * @returns {void}
+     * @memberof UnderpostRepository
+     */
+    declareSafeDirectory(repoPath) {
+      const declared = shellExec(`git config --global --get-all safe.directory`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      });
+      if (`${declared ?? ''}`.split('\n').some((entry) => entry.trim() === repoPath)) return;
+      shellExec(`git config --global --add safe.directory "${repoPath}"`, { silent: true });
+    },
+
+    /**
+     * Materializes a runtime's document root from the repository its conf route declares.
+     *
+     * Shared by every repository-backed runtime — {@link WpService} for WordPress site roots and
+     * {@link LamppService} for static Apache document roots — so one deployment can serve many
+     * repositories on the same host through a single provisioning contract.
+     *
+     * Idempotent: an existing directory is left alone, and the clone lands on a temporary path
+     * first so an interrupted run never leaves a partial tree at the document root.
+     *
+     * @param {object} opts
+     * @param {string} opts.host - Virtual-host name, for logging.
+     * @param {string} opts.siteRoot - Absolute path the checkout must occupy.
+     * @param {string} opts.repository - Repository URL or `owner/repo` short form.
+     * @param {string} [opts.owner='daemon:daemon'] - Filesystem owner of the served tree.
+     * @returns {{accessible: boolean, cloned: boolean}} Whether the remote answered, and whether
+     *   this call created the checkout.
+     * @memberof UnderpostRepository
+     */
+    provisionSiteRoot({ host, siteRoot, repository, owner = 'daemon:daemon' }) {
+      // An `env:` reference to a variable the process never received resolves to an empty string,
+      // so a conf fault and an unreachable remote arrive here as the same falsy value. Reported
+      // together they read as a GitHub problem and send the search to the wrong place.
+      const reference = `${repository ?? ''}`.trim();
+      if (!reference) {
+        logger.error(
+          `${host}: no repository resolved for ${siteRoot} — the conf route's reference is empty, ` +
+            `so its 'env:' variable is missing from this process's environment`,
+        );
+        return { accessible: false, cloned: false };
+      }
+
+      if (!process.env.GITHUB_TOKEN && Underpost.repo.repoUrlFactory(reference).startsWith('https://github.com/'))
+        logger.warn(`${host}: GITHUB_TOKEN not set — git operations will fail for private repositories`);
+
+      if (!Underpost.repo.isRemoteRepo(reference)) {
+        logger.warn(`${host}: remote repository not accessible (${reference})`);
+        return { accessible: false, cloned: false };
+      }
+      // Provisioned means a checkout is there, not merely that the path is. The runtime image
+      // ships the document-root directories, so an existence test calls every fresh pod already
+      // provisioned, skips the clone, and leaves Apache serving 403 from a directory nothing
+      // populates. `.git` is the only mark that the declared repository actually landed here.
+      if (fs.existsSync(`${siteRoot}/.git`)) {
+        logger.info(`${host}: repo already present at ${siteRoot}`);
+        return { accessible: true, cloned: false };
+      }
+      const populateInPlace = fs.existsSync(siteRoot);
+      if (populateInPlace) logger.warn(`${host}: ${siteRoot} holds no checkout; provisioning ${reference} into it`);
+
+      logger.info(`${host}: cloning ${reference} → ${siteRoot}`);
+      const tmp = `${siteRoot}.tmp`;
+      if (fs.existsSync(tmp)) shellExec(`sudo rm -rf "${tmp}"`);
+      fs.mkdirSync(path.dirname(siteRoot), { recursive: true });
+      const auth = Underpost.repo.gitAuthFactory(reference);
+      shellExec(`git clone "${auth.url}" "${tmp}"`, { env: auth.env });
+      // Copied into a directory that already exists rather than renamed over it: that directory
+      // can be image-provided or a mount point, and a rename onto one fails where a copy works.
+      if (populateInPlace) {
+        shellExec(`sudo cp -a "${tmp}/." "${siteRoot}/"`);
+        shellExec(`sudo rm -rf "${tmp}"`);
+      } else shellExec(`sudo mv "${tmp}" "${siteRoot}"`);
+      shellExec(`sudo chmod -R 755 "${siteRoot}"`);
+      shellExec(`sudo chown -R ${owner} "${siteRoot}"`);
+      return { accessible: true, cloned: true };
+    },
+
     /**
      * Resolves the in-pod site-root directory where a conf route's repository lives.
      *
@@ -1701,7 +1928,7 @@ Prevent build private config repo.`,
     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';
+      const githubUsername = repositoryIdentityFactory().owner;
 
       if (!githubToken) {
         logger.warn('backupPodRepositories: GITHUB_TOKEN not available — git push will fail');
@@ -1760,7 +1987,7 @@ Prevent build private config repo.`,
             `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`,
+            `cd /home/dd/engine && node bin host clean --force`,
           ].join(' && ');
 
           try {
@@ -1805,7 +2032,7 @@ Prevent build private config repo.`,
         throw new Error('privateEngineRepoFactory: GITHUB_USERNAME not set');
       }
 
-      const repoName = effectiveDeployId ? `engine-${effectiveDeployId.split('-')[1]}-private` : 'engine-private';
+      const repoName = Underpost.repo.privateRepoFactory(effectiveDeployId);
       logger.info(`engine-private missing — cloning ${username}/${repoName}`);
       shellExec(`underpost clone ${username}/${repoName}`);
       if (!fs.existsSync(`./${repoName}`)) {
@@ -1832,11 +2059,11 @@ Prevent build private config repo.`,
 
     /**
      * Resolves the GitHub repository for a given instance runtime by scanning
-     * every `conf.instances.json` listed in `./engine-private/deploy/dd.router`.
+     * every `conf.instances.json` listed in `./engine-private/deploy/dd.routes`.
      *
      * 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
+     *  2. Iterates each deploy ID found in `dd.routes` 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.
@@ -1853,14 +2080,7 @@ Prevent build private config repo.`,
       // (docker-image.<runtime>.dev.ci.yml) but resolves to the same instance
       // repo as its production counterpart, so strip it before matching.
       runtime = runtime.replace(/\.dev$/, '');
-      const ddRouter = './engine-private/deploy/dd.router';
-      const deployIds = fs.existsSync(ddRouter)
-        ? fs
-            .readFileSync(ddRouter, 'utf8')
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean)
-        : [];
+      const deployIds = readDeployRoutes();
       for (const deployId of deployIds) {
         const confPath = `./engine-private/conf/${deployId}/conf.instances.json`;
         if (!fs.existsSync(confPath)) continue;
@@ -1928,8 +2148,11 @@ Prevent build private config repo.`,
         logger.info('[sparseCheckoutDirectory] path already present, skipping', localPath);
         return false;
       }
-      const authUrl = `https://${process.env.GITHUB_TOKEN}@github.com/${repoOwner}/${repoName}.git`;
-      shellExec(`git clone --depth 1 --no-checkout ${authUrl} ${targetDir}`, { disableLog: true });
+      const auth = Underpost.repo.gitAuthFactory(`https://github.com/${repoOwner}/${repoName}.git`);
+      shellExec(`git clone --depth 1 --no-checkout "${auth.url}" ${targetDir}`, {
+        disableLog: true,
+        env: auth.env,
+      });
       shellExec(`cd ${targetDir} && git sparse-checkout set ${subPath} && git checkout`, { disableLog: true });
       logger.info('[sparseCheckoutDirectory] sparse checkout complete', localPath);
       return true;