@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/server/{conf.js → runtime/conf.js}

@@ -1,7 +1,7 @@
 /**
  * Provides utilities for building, loading, and managing server configurations,
  * deployment contexts, and service configurations (API, Client, WS).
- * @module src/server/conf.js
+ * @module src/server/runtime/conf.js
  * @namespace ServerConfBuilder
  */
 
@@ -13,21 +13,30 @@ import {
   getDirname,
   newInstance,
   orderAbc,
-  orderArrayFromAttrInt,
-  range,
   timer,
-} from '../client/components/core/CommonJs.js';
+} from '../../client/components/core/CommonJs.js';
 import * as dir from 'path';
 import net from 'net';
 import crypto from 'crypto';
 import colors from 'colors';
-import { loggerFactory } from './logger.js';
-import { writeEnv } from './environment.js';
-import { shellExec } from './process.js';
-import { UNDERPOST_GATEWAY, statusPageAssetPathFactory } from './underpost-gateway.js';
-import { DefaultConf } from '../../conf.js';
+import { loggerFactory } from '../ops/logger.js';
+import { isOciRuntime, writeEnv } from './environment.js';
+import { configRejectionFactory } from './config-scope.js';
+import { shellArgumentFactory, shellExec } from './process.js';
+import { UNDERPOST_GATEWAY, statusPageAssetPathFactory } from '../network/underpost-gateway.js';
+import { COVERAGE_BUNDLE_DIRECTORY } from '../build/coverage.js';
+import { DefaultConf } from '../../../conf.js';
 import splitFile from 'split-file';
-import Underpost from '../index.js';
+import { readDeployRoutes } from '../network/router.js';
+import Underpost from '../../index.js';
+import {
+  clearAwaitDeploy,
+  getRuntimeStatus,
+  isAwaitingDeploy,
+  latchAwaitDeploy,
+  RUNTIME_STATUS,
+} from './runtime-status.js';
+import { cronDeployIdResolve } from '../ops/cron.js';
 
 colors.enable();
 
@@ -176,8 +185,8 @@ const getConfFolder = (deployId) => {
 
 /**
  * Resolves the full path to a specific configuration JSON file for a deploy ID.
- * For `server` configs in development mode with a subConf, it will prefer the
- * dev-specific variant if it exists.
+ * For `server` configs it prefers the `dev.<subConf>` variant when one exists: always for a
+ * sub-conf the caller named, and only in development for one inherited from `DEPLOY_SUB_CONF`.
  *
  * @method getConfFilePath
  * @param {string} deployId - The deploy ID.
@@ -191,17 +200,28 @@ const getConfFolder = (deployId) => {
  * // => './engine-private/conf/dd-myapp/conf.server.json'
  *
  * @example
- * // In development with subConf 'local':
+ * // With an explicitly named subConf, in any environment:
  * getConfFilePath('dd-myapp', 'server', 'local');
  * // => './engine-private/conf/dd-myapp/conf.server.dev.local.json' (if it exists)
  */
 const getConfFilePath = (deployId, confType, subConf = '') => {
   const folder = getConfFolder(deployId);
-  // When no explicit subConf is given, fall back to the env var set by loadConf()
-  const effectiveSubConf = subConf || process.env.DEPLOY_SUB_CONF || '';
+  const explicit = `${subConf ?? ''}`.trim();
+  // Without an explicit sub-conf, fall back to the env var loadConf() exported.
+  const effectiveSubConf = explicit || process.env.DEPLOY_SUB_CONF || '';
   if (confType === 'server' && effectiveSubConf) {
-    const devConfPath = `${folder}/conf.${confType}.dev.${effectiveSubConf}.json`;
-    if (fs.existsSync(devConfPath)) return devConfPath;
+    // An explicitly named sub-conf is a request, not a hint: honor it whatever the ambient
+    // environment says. Only the env-var fallback stays gated on development, so a production
+    // deploy that merely carries DEPLOY_SUB_CONF is unaffected.
+    //
+    // The gate used to apply to both, and every `underpost` invocation loads the host
+    // configuration store with `override: true` — on a provisioned node that store carries
+    // NODE_ENV=production, so the gate was false for every CLI call and a named sub-conf was
+    // silently discarded in favour of the base conf.
+    if (explicit || process.env.NODE_ENV === 'development') {
+      const devConfPath = `${folder}/conf.${confType}.dev.${effectiveSubConf}.json`;
+      if (fs.existsSync(devConfPath)) return devConfPath;
+    }
   }
   return `${folder}/conf.${confType}.json`;
 };
@@ -261,7 +281,7 @@ const Config = {
       deployContext = process.env.DEPLOY_ID;
     if (!subConf && process.argv[3] && typeof process.argv[3] === 'string') subConf = process.argv[3];
 
-    Underpost.env.set('await-deploy', new Date().toISOString());
+    latchAwaitDeploy();
     if (deployContext.startsWith('dd-')) loadConf(deployContext, subConf);
     if (deployContext === 'proxy') await Config.buildProxy(deployList, subConf);
   },
@@ -269,16 +289,15 @@ const Config = {
    * @method deployIdFactory
    * @description Creates a new deploy ID.
    * @param {string} [deployId='dd-default']
-   * @param {object} [options={ subConf: '', cluster: false }] - The options.
+   * @param {object} [options={ subConf: '' }] - The options.
    * @memberof ServerConfBuilder
    */
-  deployIdFactory: function (deployId = DEFAULT_DEPLOY_ID, options = { subConf: '', cluster: false }) {
+  deployIdFactory: function (deployId = DEFAULT_DEPLOY_ID, options = { subConf: '' }) {
     if (!deployId.startsWith('dd-')) deployId = `dd-${deployId}`;
 
     logger.info('Build deployId', deployId);
 
     const folder = `./engine-private/conf/${deployId}`;
-    const repoName = `engine-${deployId.split('dd-')[1]}`;
 
     if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
 
@@ -330,29 +349,6 @@ const Config = {
       );
     }
 
-    if (options.cluster === true) {
-      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}`);
-
-      if (!fs.existsSync(`./engine-private/deploy/dd.router`))
-        fs.writeFileSync(`./engine-private/deploy/dd.router`, deployId, 'utf8');
-      else
-        fs.writeFileSync(
-          `./engine-private/deploy/dd.router`,
-          fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').trim() + `,${deployId}`,
-          'utf8',
-        );
-    }
-
     return { deployIdFolder: folder, deployId };
   },
   /**
@@ -412,17 +408,178 @@ const Config = {
  * @param {string} [subConf=''] - The sub configuration.
  * @memberof ServerConfBuilder
  */
+/**
+ * @method deployEnvFilePath
+ * @description Resolves a deployment's env file for an environment.
+ *
+ * A named sub-configuration selects `.env.<env>.<subConf>` when that file exists and degrades to
+ * the plain `.env.<env>` when it does not. Single source of this precedence: {@link loadConf}
+ * materializes the working tree from it and {@link UnderpostApp} addresses it from the CLI, so
+ * both always agree on which file is in effect.
+ * @param {string} deployId - Deployment id.
+ * @param {string} [env='production'] - Environment selector.
+ * @param {string} [subConf] - Sub-configuration name.
+ * @returns {string} Path to the deployment env file.
+ * @memberof ServerConfBuilder
+ */
+const deployEnvFilePath = (deployId, env = 'production', subConf = '') => {
+  const base = `${getConfFolder(deployId)}/.env.${env || 'production'}`;
+  const name = `${subConf ?? ''}`.trim();
+  if (!name) return base;
+  const scoped = `${base}.${name}`;
+  return fs.existsSync(scoped) ? scoped : base;
+};
+
+/**
+ * The environments a deployment's configuration actually carries.
+ *
+ * Read from the tree rather than assumed, because which environments exist is a property of the
+ * checkout: a workstation carries every one a developer runs, and a workload carries none at all —
+ * its environment is injected. A name is the segment after `.env.` and nothing further, so an
+ * overlay (`.env.production.oci`) and a sub-configuration (`.env.development.api`) are the
+ * variants of an environment, never environments of their own.
+ * @param {string} deployId - Deployment id.
+ * @returns {string[]} Environment names present, sorted.
+ * @memberof ServerConfBuilder
+ */
+const deployEnvNamesFactory = (deployId) => {
+  const folder = getConfFolder(deployId);
+  if (!fs.existsSync(folder)) return [];
+  return fs
+    .readdirSync(folder)
+    .map((entry) => `${entry}`.match(/^\.env\.([^.]+)$/)?.[1])
+    .filter(Boolean)
+    .sort();
+};
+
+/**
+ * Resolves a custom instance's env file for an environment.
+ *
+ * An instance's runtime environment is its own file, not a sub-configuration of the parent
+ * deployment's: `instance-build-manifest` writes it, the instance container sources it at boot,
+ * and {@link UnderpostApp} addresses it from the CLI through `--args instance-id=`. Single
+ * source of that path, so the three can never disagree.
+ * @param {string} deployId - Parent deployment id.
+ * @param {string} instanceId - Instance id, as declared in `conf.instances.json`.
+ * @param {string} [env='production'] - Environment selector.
+ * @returns {string} Path to the instance env file.
+ * @memberof ServerConfBuilder
+ */
+const instanceEnvFilePath = (deployId, instanceId, env = 'production') =>
+  `${getConfFolder(deployId)}/instances/${instanceId}/env/${env || 'production'}.env`;
+
+/**
+ * Suffix marking a deployment env file's OCI (container) runtime overlay.
+ * @constant {string}
+ * @memberof ServerConfBuilder
+ */
+const OCI_ENV_SUFFIX = '.oci';
+
+/**
+ * @method deployOciEnvFilePath
+ * @description Resolves a deployment's OCI runtime env overlay for an environment.
+ *
+ * The overlay is per environment, not per sub-configuration: it carries the values that only
+ * hold when the deployment runs as a container image (cluster-internal service names, in-cluster
+ * database endpoints), which are the same whichever host sub-configuration is in effect.
+ * @param {string} deployId - Deployment id.
+ * @param {string} [env='production'] - Environment selector.
+ * @returns {string} Path to the deployment's OCI env overlay.
+ * @memberof ServerConfBuilder
+ */
+const deployOciEnvFilePath = (deployId, env = 'production') =>
+  `${getConfFolder(deployId)}/.env.${env || 'production'}${OCI_ENV_SUFFIX}`;
+
+/**
+ * @method envLineKey
+ * @description The variable name a dotenv line declares, or `''` for blanks and comments.
+ * @param {string} line - One dotenv line.
+ * @returns {string} Declared key, or `''`.
+ * @memberof ServerConfBuilder
+ */
+const envLineKey = (line) => {
+  const trimmed = `${line}`.trimStart();
+  if (!trimmed || trimmed.startsWith('#')) return '';
+  const assign = trimmed.indexOf('=');
+  return assign === -1 ? '' : trimmed.slice(0, assign).trim();
+};
+
+/**
+ * @method ociEnvContentFactory
+ * @description Applies an OCI overlay onto base env contents.
+ *
+ * Textual rather than parse-and-render: base lines the overlay does not redeclare survive
+ * verbatim — comments, ordering, and value quoting included — and the overlay is appended whole,
+ * so an overridden key appears exactly once with the container value.
+ * @param {string} baseContent - The deployment's `.env.<env>` contents.
+ * @param {string} overlayContent - The matching `.env.<env>.oci` contents.
+ * @returns {string} Overlay-applied env contents.
+ * @memberof ServerConfBuilder
+ */
+const ociEnvContentFactory = (baseContent, overlayContent) => {
+  const overlay = `${overlayContent ?? ''}`.trim();
+  if (!overlay) return baseContent;
+  const overridden = new Set(overlay.split('\n').map(envLineKey).filter(Boolean));
+  const kept = `${baseContent ?? ''}`
+    .split('\n')
+    .filter((line) => {
+      const key = envLineKey(line);
+      return !key || !overridden.has(key);
+    })
+    .join('\n')
+    .trimEnd();
+  return `${kept}${kept ? '\n' : ''}${overlay}\n`;
+};
+
+/**
+ * @method deployEnvContentFactory
+ * @description Reads a deployment's env file for an environment, with its OCI overlay applied
+ * when one exists and the caller is resolving for a container runtime.
+ *
+ * Single source of the overlay precedence: {@link loadConf} materializes the working tree from
+ * it and {@link UnderpostApp} projects the cluster Secret from it, so the file a container reads
+ * and the Secret injected into it always carry the same values. Outside a container the base
+ * file is returned untouched, which is what keeps a developer host on its local endpoints.
+ * @param {string} deployId - Deployment id.
+ * @param {string} [env='production'] - Environment selector.
+ * @param {string} [subConf=''] - Sub-configuration name.
+ * @param {object} [options] - Resolution options.
+ * @param {boolean} [options.oci] - Force the overlay on or off; defaults to container detection.
+ * @returns {{source: string, overlay: string|null, content: string, values: Object<string,string>}}
+ *   The base file used, the overlay applied (or `null`), and the resulting contents and values.
+ * @memberof ServerConfBuilder
+ */
+const deployEnvContentFactory = (deployId, env = 'production', subConf = '', options = {}) => {
+  const source = deployEnvFilePath(deployId, env, subConf);
+  const baseContent = fs.readFileSync(source, 'utf8');
+  const overlayPath = deployOciEnvFilePath(deployId, env);
+  const applyOverlay = (options.oci ?? isOciRuntime()) && fs.existsSync(overlayPath);
+  if (!applyOverlay) return { source, overlay: null, content: baseContent, values: dotenv.parse(baseContent) };
+  const content = ociEnvContentFactory(baseContent, fs.readFileSync(overlayPath, 'utf8'));
+  return { source, overlay: overlayPath, content, values: dotenv.parse(content) };
+};
+
+/**
+ * @method cleanDeployEnvFiles
+ * @description Removes the working-tree env files {@link loadConf} materializes.
+ * Single source of the file list, shared with the app domain's `clean` action.
+ * @returns {Array<string>} The paths that were present and removed.
+ * @memberof ServerConfBuilder
+ */
+const cleanDeployEnvFiles = () => {
+  const targets = ['./.env', './.env.production', './.env.development', './.env.test'];
+  const present = targets.filter((target) => fs.existsSync(target));
+  for (const target of present) fs.removeSync(target);
+  return present;
+};
+
 const loadConf = (deployId = DEFAULT_DEPLOY_ID, subConf) => {
   if (deployId === 'current') {
     console.log(process.env.DEPLOY_ID);
     return;
   }
   if (deployId === 'clean') {
-    const path = '.';
-    fs.removeSync(`${path}/.env`);
-    fs.removeSync(`${path}/.env.production`);
-    fs.removeSync(`${path}/.env.development`);
-    fs.removeSync(`${path}/.env.test`);
+    cleanDeployEnvFiles();
     return;
   }
   const folder = getConfFolder(deployId);
@@ -432,34 +589,58 @@ const loadConf = (deployId = DEFAULT_DEPLOY_ID, subConf) => {
   if (subConf) process.env.DEPLOY_SUB_CONF = subConf;
 
   for (const typeConf of Object.keys(Config.default)) {
-    let srcConf = fs.readFileSync(`${folder}/conf.${typeConf}.json`, 'utf8');
-    if (process.env.NODE_ENV === 'development' && typeConf === 'server' && subConf) {
-      const devConfPath = `${folder}/conf.${typeConf}.dev${subConf ? `.${subConf}` : ''}.json`;
+    const confPath = `${folder}/conf.${typeConf}.json`;
+    let srcConf;
+    if (fs.existsSync(confPath)) srcConf = fs.readFileSync(confPath, 'utf8');
+    else {
+      Config.default[typeConf] = newInstance(DefaultConf[typeConf]);
+      continue;
+    }
+    // Same precedence as getConfFilePath, so loadConf and every later read agree on which file
+    // is in effect: a sub-conf named here was named by the caller, so it is not gated on the
+    // ambient environment.
+    if (typeConf === 'server' && subConf) {
+      const devConfPath = getConfFilePath(deployId, typeConf, subConf);
       if (fs.existsSync(devConfPath)) srcConf = fs.readFileSync(devConfPath, 'utf8');
     }
     let parsed = JSON.parse(srcConf);
     if (typeConf === 'server') parsed = loadReplicas(deployId, parsed);
     Config.default[typeConf] = parsed;
   }
-  fs.writeFileSync(`./.env.production`, fs.readFileSync(`${folder}/.env.production`, 'utf8'), 'utf8');
-  fs.writeFileSync(`./.env.development`, fs.readFileSync(`${folder}/.env.development`, 'utf8'), 'utf8');
-  fs.writeFileSync(`./.env.test`, fs.readFileSync(`${folder}/.env.test`, 'utf8'), 'utf8');
-  const NODE_ENV = process.env.NODE_ENV || 'development';
-  if (NODE_ENV) {
-    const subPathEnv = fs.existsSync(`${folder}/.env.${NODE_ENV}.${subConf}`)
-      ? `${folder}/.env.${NODE_ENV}.${subConf}`
-      : `${folder}/.env.${NODE_ENV}`;
-    fs.writeFileSync(`./.env`, fs.readFileSync(subPathEnv, 'utf8'), 'utf8');
-    const env = dotenv.parse(fs.readFileSync(subPathEnv, 'utf8'));
-    process.env = {
-      ...process.env,
-      ...env,
-    };
-  }
+  // Each materialized copy carries its own OCI overlay, so a container that later switches
+  // NODE_ENV still reads container values rather than the host endpoints of the base file.
+  const available = deployEnvNamesFactory(deployId);
+  for (const name of available)
+    fs.writeFileSync(`./.env.${name}`, deployEnvContentFactory(deployId, name).content, 'utf8');
+
+  const envName = process.env.NODE_ENV || 'development';
+  // A tree with no environment of its own is a workload: its configuration is injected, and
+  // materializing is neither possible nor wanted. A tree that carries environments but not this
+  // one is a mistake worth naming — falling through would run the deployment against whichever
+  // environment happened to be loaded.
+  if (available.length > 0) {
+    if (!available.includes(envName))
+      throw new Error(
+        configRejectionFactory({
+          domain: 'app',
+          deployId,
+          env: envName,
+          key: 'NODE_ENV',
+          reason: `no environment source; ${getConfFolder(deployId)} carries ${available.join(', ')}`,
+        }),
+      );
+    const { content, values } = deployEnvContentFactory(deployId, envName, subConf);
+    fs.writeFileSync(`./.env`, content, 'utf8');
+    process.env = { ...process.env, ...values, NODE_ENV: envName };
+  } else process.env.NODE_ENV = envName;
   const originPackageJson = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
   const packageJson = JSON.parse(fs.readFileSync(`${folder}/package.json`, 'utf8'));
   originPackageJson.scripts.start = packageJson.scripts.start;
   packageJson.scripts = originPackageJson.scripts;
+  // `bin` is engine identity, not deploy identity: it is what `npm link` publishes as the
+  // global `underpost` command. Deploy manifests do not carry one, so without this the
+  // checkout would stop being linkable the moment its environment was loaded.
+  if (originPackageJson.bin) packageJson.bin = originPackageJson.bin;
   fs.writeFileSync(`./package.json`, JSON.stringify(packageJson, null, 4), 'utf8');
   return { folder, deployId };
 };
@@ -830,247 +1011,6 @@ const cloneSrcComponents = async ({ toOptions, fromOptions }) => {
   }
 };
 
-/**
- * @method buildProxyRouter
- * @description Builds the proxy router.
- * @memberof ServerConfBuilder
- */
-const buildProxyRouter = () => {
-  const confServer = newInstance(Config.default.server);
-  let currentPort = parseInt(process.env.PORT) + 1;
-  const proxyRouter = {};
-  for (const host of Object.keys(confServer)) {
-    for (const path of Object.keys(confServer[host])) {
-      if (confServer[host][path].singleReplica) continue;
-
-      if (isDevProxyContext()) confServer[host][path].proxy = [isTlsDevProxy() ? 443 : 80];
-
-      confServer[host][path].port = newInstance(currentPort);
-      for (const port of confServer[host][path].proxy) {
-        if (!(port in proxyRouter)) proxyRouter[port] = {};
-        proxyRouter[port][`${host}${path}`] = {
-          // target: `http://${host}:${confServer[host][path].port}${path}`,
-          target: `http://localhost:${confServer[host][path].port}`,
-          // target: `http://127.0.0.1:${confServer[host][path].port}`,
-          proxy: confServer[host][path].proxy,
-          redirect: confServer[host][path].redirect,
-          host,
-          path,
-        };
-      }
-      currentPort++;
-      if (confServer[host][path].peer) {
-        const peerPath = path === '/' ? `/peer` : `${path}/peer`;
-        confServer[host][peerPath] = newInstance(confServer[host][path]);
-        confServer[host][peerPath].port = newInstance(currentPort);
-        for (const port of confServer[host][path].proxy) {
-          if (!(port in proxyRouter)) proxyRouter[port] = {};
-          proxyRouter[port][`${host}${peerPath}`] = {
-            // target: `http://${host}:${confServer[host][peerPath].port}${peerPath}`,
-            target: `http://localhost:${confServer[host][peerPath].port}`,
-            // target: `http://127.0.0.1:${confServer[host][peerPath].port}`,
-            proxy: confServer[host][peerPath].proxy,
-            host,
-            path: peerPath,
-          };
-        }
-        currentPort++;
-      }
-    }
-  }
-
-  return proxyRouter;
-};
-
-/**
- * @method pathPortAssignmentFactory
- * @description Creates the path port assignment.
- * @param {string} deployId - The deploy ID.
- * @param {object} router - The router.
- * @param {object} confServer - The server configuration.
- * @memberof ServerConfBuilder
- */
-const pathPortAssignmentFactory = async (deployId, router, confServer) => {
-  const pathPortAssignmentData = {};
-  for (const host of Object.keys(confServer)) {
-    const pathPortAssignment = [];
-    for (const path of Object.keys(confServer[host])) {
-      const { peer } = confServer[host][path];
-      if (!router[`${host}${path === '/' ? '' : path}`]) continue;
-      const port = parseInt(router[`${host}${path === '/' ? '' : path}`].split(':')[2]);
-      // logger.info('', { host, port, path });
-      pathPortAssignment.push({
-        port,
-        path,
-      });
-
-      if (peer) {
-        //  logger.info('', { host, port: port + 1, path: '/peer' });
-        pathPortAssignment.push({
-          port: port + 1,
-          path: `${path === '/' ? '' : path}/peer`,
-        });
-      }
-    }
-    pathPortAssignmentData[host] = pathPortAssignment;
-  }
-  if (fs.existsSync(`./engine-private/replica`)) {
-    const singleReplicas = await fs.readdir(`./engine-private/replica`);
-    for (let replica of singleReplicas) {
-      if (replica.startsWith(deployId)) {
-        const replicaServerConf = loadConfServerJson(`./engine-private/replica/${replica}/conf.server.json`);
-        for (const host of Object.keys(replicaServerConf)) {
-          const pathPortAssignment = [];
-          for (const path of Object.keys(replicaServerConf[host])) {
-            const { peer } = replicaServerConf[host][path];
-            if (!router[`${host}${path === '/' ? '' : path}`]) continue;
-            const port = parseInt(router[`${host}${path === '/' ? '' : path}`].split(':')[2]);
-            // logger.info('', { host, port, path });
-            pathPortAssignment.push({
-              port,
-              path,
-            });
-
-            if (peer) {
-              //  logger.info('', { host, port: port + 1, path: '/peer' });
-              pathPortAssignment.push({
-                port: port + 1,
-                path: `${path === '/' ? '' : path}/peer`,
-              });
-            }
-          }
-          pathPortAssignmentData[host] = pathPortAssignmentData[host].concat(pathPortAssignment);
-        }
-      }
-    }
-  }
-  return pathPortAssignmentData;
-};
-
-/**
- * @method deployRangePortFactory
- * @description Creates the deploy range port factory.
- * @param {object} router - The router.
- * @returns {object} - The deploy range port factory.
- * @memberof ServerConfBuilder
- */
-const deployRangePortFactory = (router) => {
-  const ports = Object.values(router).map((p) => parseInt(p.split(':')[2]));
-  const fromPort = Math.min(...ports);
-  const toPort = Math.max(...ports);
-  return { ports, fromPort, toPort };
-};
-
-/**
- * @method buildKindPorts
- * @description Builds the kind ports.
- * @param {number} from - The from port.
- * @param {number} to - The to port.
- * @returns {string} - The kind ports.
- * @memberof ServerConfBuilder
- */
-const buildKindPorts = (from, to) =>
-  range(parseInt(from), parseInt(to))
-    .map(
-      (port) => `    - name: 'tcp-${port}'
-      protocol: TCP
-      port: ${port}
-      targetPort: ${port}
-    - name: 'udp-${port}'
-      protocol: UDP
-      port: ${port}
-      targetPort: ${port}
-`,
-    )
-    .join('\n');
-
-/**
- * @method buildPortProxyRouter
- * @description Builds the port proxy router.
- * @param {object} options - The options.
- * @param {number} [options.port=4000] - The port.
- * @param {object} options.proxyRouter - The proxy router.
- * @param {object} [options.hosts] - The hosts.
- * @param {boolean} [options.orderByPathLength=false] - Whether to order by path length.
- * @param {boolean} [options.devProxyContext=false] - Whether to use dev proxy context.
- * @returns {object} - The port proxy router.
- * @memberof ServerConfBuilder
- */
-const buildPortProxyRouter = (
-  options = { port: 4000, proxyRouter, hosts, orderByPathLength: false, devProxyContext: false },
-) => {
-  let { port, proxyRouter, hosts, orderByPathLength } = options;
-  hosts = hosts || proxyRouter[port] || {};
-
-  const router = {};
-  // build router
-  Object.keys(hosts).map((hostKey) => {
-    let { host, path, target, proxy, peer } = hosts[hostKey];
-
-    if (!proxy.includes(port)) {
-      logger.warn('Proxy port not set on conf', { port, host, path, proxy, target });
-      if (process.env.NODE_ENV === 'production') {
-        logger.warn('Omitting host', { host, path, target });
-        return;
-      }
-    }
-    // ${process.env.NODE_ENV === 'development' && !isDevProxyContext() ? `:${port}` : ''}
-    const absoluteHost = [80, 443].includes(port)
-      ? `${host}${path === '/' ? '' : path}`
-      : `${host}:${port}${path === '/' ? '' : path}`;
-
-    if (absoluteHost in router)
-      logger.warn('Overwrite: Absolute host already exists on router', { absoluteHost, target });
-
-    if (options.devProxyContext === true) {
-      const appDevPort = parseInt(target.split(':')[2]) - process.env.DEV_PROXY_PORT_OFFSET;
-      router[absoluteHost] = `http://localhost:${appDevPort}`;
-    } else router[absoluteHost] = target;
-  }); // order router
-
-  if (Object.keys(router).length === 0) return router;
-
-  const devApiConfPath = `./engine-private/conf/${process.argv[3]}/conf.server.dev.${process.argv[4]}-dev-api.json`;
-  if (options.devProxyContext === true && process.env.NODE_ENV === 'development' && fs.existsSync(devApiConfPath)) {
-    const confDevApiServer = JSON.parse(fs.readFileSync(devApiConfPath, 'utf8'));
-    let devApiHosts = [];
-    let origins = [];
-    for (const _host of Object.keys(confDevApiServer))
-      for (const _path of Object.keys(confDevApiServer[_host])) {
-        if (confDevApiServer[_host][_path].origins && confDevApiServer[_host][_path].origins.length) {
-          origins.push(...confDevApiServer[_host][_path].origins);
-          if (_path !== 'peer' && devApiHosts.length === 0)
-            devApiHosts.push(
-              `${_host}${[80, 443].includes(port) && isDevProxyContext() ? '' : `:${port}`}${_path == '/' ? '' : _path}`,
-            );
-        }
-      }
-    origins = Array.from(new Set(origins));
-    console.log({
-      origins,
-      devApiHosts,
-    });
-    for (const devApiHost of devApiHosts) {
-      if (devApiHost in router) {
-        const target = router[devApiHost];
-        delete router[devApiHost];
-        router[`${devApiHost}/${process.env.BASE_API}`] = target;
-        router[`${devApiHost}/socket.io`] = target;
-        for (const origin of origins) router[devApiHost] = origin;
-      }
-    }
-  }
-
-  if (orderByPathLength === true) {
-    const reOrderRouter = {};
-    for (const absoluteHostKey of orderArrayFromAttrInt(Object.keys(router), 'length'))
-      reOrderRouter[absoluteHostKey] = router[absoluteHostKey];
-    return reOrderRouter;
-  }
-
-  return router;
-};
-
 /**
  * @method buildReplicaId
  * @description Builds the replica ID.
@@ -1098,17 +1038,7 @@ const getDataDeploy = async (
     disableSyncEnvPort: false,
   },
 ) => {
-  let dataDeploy = fs
-    .readFileSync(`./engine-private/deploy/dd.router`, 'utf8')
-    .split(',')
-    .map((deployId) => deployId.trim())
-    .filter((deployId) => deployId);
-
-  dataDeploy = dataDeploy.map((deployId) => {
-    return {
-      deployId,
-    };
-  });
+  let dataDeploy = readDeployRoutes().map((deployId) => ({ deployId }));
 
   if (options && options.buildSingleReplica && fs.existsSync(`./engine-private/replica`))
     fs.removeSync(`./engine-private/replica`);
@@ -1125,7 +1055,7 @@ const getDataDeploy = async (
       for (const path of Object.keys(serverConf[host])) {
         if (!isReplicaDeploy && serverConf[host][path].replicas && serverConf[host][path].singleReplica) {
           if (options && options.buildSingleReplica)
-            await Underpost.repo.client(deployObj.deployId, '', host, path, {
+            await Underpost.client.callback(deployObj.deployId, '', host, path, {
               singleReplica: true,
             });
           replicaDataDeploy = replicaDataDeploy.concat(
@@ -1143,7 +1073,7 @@ const getDataDeploy = async (
   }
 
   if (!options.disableSyncEnvPort && options.buildSingleReplica)
-    await Underpost.repo.client(undefined, '', '', '', { syncEnvPort: true });
+    await Underpost.client.callback(undefined, '', '', '', { syncEnvPort: true });
 
   logger.info('Deployments configured', buildDataDeploy);
 
@@ -1168,7 +1098,7 @@ const validateTemplatePath = (absolutePath = '') => {
   const clients = DefaultConf.client.default.services;
 
   if (
-    absolutePath.match('src/api') &&
+    absolutePath.match('src/api/') &&
     !absolutePath.match('src/api/types.js') &&
     !confServer.apis.find((p) => absolutePath.match(`src/api/${p}/`))
   ) {
@@ -1243,11 +1173,11 @@ const validateTemplatePath = (absolutePath = '') => {
  * @memberof ServerConfBuilder
  */
 const awaitDeployMonitor = async (isFinal = false, deltaMs = 1000, callback = false) => {
-  if (!callback) Underpost.env.set('await-deploy', new Date().toISOString());
+  if (!callback) latchAwaitDeploy();
   if (isFinal) logger.info('Final deployment running (no replica)');
   await timer(deltaMs);
-  if (Underpost.env.get('container-status') === 'error') return false;
-  if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor(false, deltaMs, true);
+  if (getRuntimeStatus() === RUNTIME_STATUS.ERROR) return false;
+  if (isAwaitingDeploy()) return await awaitDeployMonitor(false, deltaMs, true);
   return true;
 };
 
@@ -1564,35 +1494,49 @@ const getInstanceContext = async (options = { deployId, singleReplica, replicas,
  * @param {string} options.host - The host.
  * @param {string} options.path - The path.
  * @param {string} options.origin - The origin.
- * @returns {object} - The API configuration.
+ * @returns {Promise<string|undefined>} The derived sub-conf id (`<subConf>-dev-api`), or
+ *   undefined when no client origin was given and nothing was derived.
  * @memberof ServerConfBuilder
  */
 const buildApiConf = async (options = { deployId: '', subConf: '', host: '', path: '', origin: '' }) => {
   let { deployId, subConf, host, path, origin } = options;
-  if (!deployId) deployId = process.argv[2].trim();
-  if (!subConf) subConf = process.argv[3].trim();
-  if (process.argv[4]) host = process.argv[4].trim();
-  if (process.argv[5]) path = process.argv[5].trim();
+  // The client origin is what selects this mode, so it is resolved before
+  // anything else: `src/api.js` also runs without any of these positionals.
   if (process.argv[6])
     origin = `${process.env.NODE_ENV === 'production' ? 'https' : 'http'}://${process.argv[6].trim()}`;
-
-  if (!origin) return;
+  if (!origin) return undefined;
+  if (!deployId) deployId = process.argv[2]?.trim();
+  if (!subConf) subConf = process.argv[3]?.trim();
+  if (process.argv[4]) host = process.argv[4].trim();
+  if (process.argv[5]) path = process.argv[5].trim();
+  if (!deployId || !subConf || !host || !path) {
+    logger.warn('Skipping api conf; a client origin needs deploy-id, sub-conf, host and path', {
+      deployId,
+      subConf,
+      host,
+      path,
+      origin,
+    });
+    return undefined;
+  }
   const confServer = JSON.parse(
     fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.dev.${subConf}.json`, 'utf8'),
   );
   const envObj = dotenv.parse(
     fs.readFileSync(`./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}`, 'utf8'),
   );
-  if (host && path) {
-    confServer[host][path].origins = [origin];
-    logger.info('Build api conf', { host, path, origin });
-  } else return;
-  writeEnv(`./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}.${subConf}-dev-api`, envObj);
+  if (!confServer[host]?.[path])
+    throw new Error(`No ${host}${path} instance in conf.server.dev.${subConf}.json for ${deployId}`);
+  confServer[host][path].origins = [origin];
+  logger.info('Build api conf', { host, path, origin });
+  const devApiSubConf = `${subConf}-dev-api`;
+  writeEnv(`./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}.${devApiSubConf}`, envObj);
   fs.writeFileSync(
-    `./engine-private/conf/${deployId}/conf.server.dev.${subConf}-dev-api.json`,
+    `./engine-private/conf/${deployId}/conf.server.dev.${devApiSubConf}.json`,
     JSON.stringify(confServer, null, 4),
     'utf8',
   );
+  return devApiSubConf;
 };
 
 /**
@@ -1616,12 +1560,19 @@ const buildClientStaticConf = async (
   if (!subConf) subConf = process.argv[3].trim();
   if (!host) host = process.argv[4].trim();
   if (!path) path = process.argv[5].trim();
-  const confServer = JSON.parse(
-    fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.dev.${subConf}-dev-api.json`, 'utf8'),
-  );
-  const envObj = dotenv.parse(
-    fs.readFileSync(`./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}.${subConf}-dev-api`, 'utf8'),
-  );
+  // The API server derives these two files, and it derives them only when it is
+  // given the client origin. Their absence means that step has not run, which is
+  // a setup order to state rather than an ENOENT to decode.
+  const confPath = `./engine-private/conf/${deployId}/conf.server.dev.${subConf}-dev-api.json`;
+  const envPath = `./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}.${subConf}-dev-api`;
+  for (const source of [confPath, envPath])
+    if (!fs.existsSync(source))
+      throw new Error(
+        `Missing ${source}. Start the API server first, with the client origin as its last argument: ` +
+          `npm run dev:api ${deployId} ${subConf} ${host} ${path} <client-host:port>`,
+      );
+  const confServer = JSON.parse(fs.readFileSync(confPath, 'utf8'));
+  const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
   envObj.PORT = parseInt(envObj.PORT);
   const apiBaseHost = devProxy
     ? devProxyHostFactory({ host, tls: isTlsDevProxy() })
@@ -1640,16 +1591,6 @@ const buildClientStaticConf = async (
   );
 };
 
-/**
- * @method isDeployRunnerContext
- * @description Checks if the deploy runner context is valid.
- * @param {string} path - The path.
- * @param {object} options - The options.
- * @returns {boolean} - The deploy runner context.
- * @memberof ServerConfBuilder
- */
-const isDeployRunnerContext = (path, options) => !options.build && path && path !== 'template-deploy';
-
 /**
  * @method isDevProxyContext
  * @description Checks if the dev proxy context is valid.
@@ -1860,7 +1801,7 @@ const dispatchBuildInstanceEnv = ({
 const loadProjectInstanceEnvBuilder = async (deployId) => {
   const match = /^dd-([a-z0-9][a-z0-9-]*)$/.exec(`${deployId || ''}`);
   if (!match) return null;
-  const moduleUrl = new URL(`../projects/${match[1]}/instance-data.js`, import.meta.url);
+  const moduleUrl = new URL(`../../projects/${match[1]}/instance-data.js`, import.meta.url);
   if (!fs.existsSync(moduleUrl)) return null;
   const projectModule = await import(moduleUrl.href);
   if (projectModule.buildInstanceEnv === undefined) return null;
@@ -2382,6 +2323,56 @@ const curlStatusChainFactory = (raw = '') => {
   return chain;
 };
 
+/**
+ * @method publicIngressProbeFactory
+ * @description Probes one public URL the way the traffic report does.
+ *
+ * `-L` follows the real redirect chain, `-v` supplies one response line per hop,
+ * `-i` keeps full response headers available, and `-s` removes only the progress
+ * meter. The body is discarded so a report stays bounded even when a host
+ * returns a large application page. One implementation, because the traffic
+ * table and the ingress event have to agree on what "reachable" means.
+ * @param {string} url - Absolute URL to probe.
+ * @returns {Array<string>} Ordered response codes; `['000']` when nothing answered.
+ * @memberof ServerConfBuilder
+ */
+const publicIngressProbeFactory = (url) => {
+  if (!url) return ['000'];
+  const argument = shellArgumentFactory(url);
+  return curlStatusChainFactory(
+    shellExec(
+      `curl -L -v -i -s --connect-timeout 3 --max-time 12 --max-redirs 10 ` +
+        `-o /dev/null -w '\nUNDERPOST_CURL_FINAL=%{http_code}\n' ${argument} 2>&1 || true`,
+      { stdout: true, silent: true, silentOnError: true, disableLog: true },
+    ),
+  );
+};
+
+/**
+ * @method publicIngressUrlsFactory
+ * @description Every public URL a deploy list publishes, from the same conf the
+ * traffic report reads.
+ * @param {string[]} [deployList] - Deploy ids.
+ * @param {string} [env='production'] - Environment whose routes are published.
+ * @returns {Array<{host: string, path: string, url: string}>} Distinct routable URLs.
+ * @memberof ServerConfBuilder
+ */
+const publicIngressUrlsFactory = (deployList = [], env = 'production') => {
+  const urls = new Map();
+  for (const deployId of deployList)
+    for (const entry of deployTrafficEntriesFactory({ deployId, env }))
+      for (const routePath of `${entry.path || '/'}`.split(' ').filter(Boolean)) {
+        const path = routePath.startsWith('/') ? routePath : `/${routePath}`;
+        try {
+          const url = new URL(path, `https://${entry.host}`).href;
+          if (!urls.has(url)) urls.set(url, { host: entry.host, path, url });
+        } catch {
+          /* a host the conf cannot turn into a URL is not routable */
+        }
+      }
+  return [...urls.values()];
+};
+
 /**
  * @method trafficTableRowsFactory
  * @description Resolves the live colour of each routable deployment, optionally
@@ -2464,6 +2455,25 @@ const hostRenderInstancesFactory = ({ declared = [], preserved = [], isDeployed
 const isTrafficServingFactory = ({ liveTraffic = '', hasReadyEndpoints = () => false }) =>
   !!liveTraffic && hasReadyEndpoints(liveTraffic);
 
+/**
+ * @method redeployPlanFactory
+ * @description The colour a redeploy targets, and how that colour is brought up.
+ *
+ * The inactive colour has no Deployment for most of a blue/green cycle: `run sync`
+ * deletes it before publishing the maintenance route, and a promote leaves only
+ * the colour it routed to. So a `rollout restart` of the target is a NotFound
+ * error on exactly the state blue/green is meant to be in, and its absence has to
+ * select building that colour instead of failing the deploy.
+ * @param {string} [liveTraffic] - Colour currently routed, or empty when none is.
+ * @param {Function} hasDeployment - `(colour) => boolean`.
+ * @returns {{targetTraffic: string, create: boolean}} Colour to deploy, and whether it must be created rather than restarted.
+ * @memberof ServerConfBuilder
+ */
+const redeployPlanFactory = ({ liveTraffic = '', hasDeployment = () => false }) => {
+  const targetTraffic = nextTrafficFactory(liveTraffic);
+  return { targetTraffic, create: !hasDeployment(targetTraffic) };
+};
+
 /**
  * @method instanceTrafficPlanFactory
  * @description Resolves, for each instance, the colour routed now and the colour
@@ -2931,39 +2941,14 @@ ${renderHosts}`,
   return { renderHosts, changed: true };
 };
 
-/**
- * Resolves the concrete deploy ids a build or conf-sync run should iterate over.
- *
- * The meta deploy id `dd` fans out to the comma separated ids declared in
- * `engine-private/deploy/dd.router`; when that file is absent (e.g. the private
- * repository is not checked out) it falls back to {@link ServerConfBuilder.DEFAULT_DEPLOY_ID}.
- * Any other value is parsed as a comma separated list.
- * Entries are trimmed and empties dropped.
- *
- * @method resolveDeployList
- * @param {string} deployId - A deploy id, a comma separated list, or the `dd` meta id.
- * @returns {string[]} Ordered list of concrete deploy ids.
- * @memberof ServerConfBuilder
- */
-const resolveDeployList = (deployId) =>
-  (deployId === 'dd'
-    ? fs.existsSync('./engine-private/deploy/dd.router')
-      ? fs.readFileSync('./engine-private/deploy/dd.router', 'utf8')
-      : DEFAULT_DEPLOY_ID
-    : deployId
-  )
-    .split(',')
-    .map((id) => id.trim())
-    .filter(Boolean);
-
 /**
  * Syncs a single deploy id's private configuration into its dedicated
  * `engine-<suffix>-private` repository and pushes the result.
  *
  * Idempotent and safe to rerun: the private repo is cloned when missing or reset to a clean
- * checkout when present, then the deploy id's `conf` folder, matching `replica` and
- * `itc-scripts` entries, and any caller-supplied `extraPaths` payloads are mirrored. The
- * commit/push step is a no-op when nothing changed (`silentOnError`).
+ * checkout when present, then the deploy id's `conf` folder (its `.env.<env>.oci` runtime
+ * overlays included), matching `replica` entries, and any caller-supplied `extraPaths` payloads
+ * are mirrored. The commit/push step is a no-op when nothing changed (`silentOnError`).
  *
  * @method syncPrivateConf
  * @param {string} deployId - A concrete deploy id (e.g. `dd-cyberia`), not the `dd` meta id.
@@ -2973,10 +2958,10 @@ const resolveDeployList = (deployId) =>
  * @memberof ServerConfBuilder
  */
 const syncPrivateConf = (deployId, extraPaths = []) => {
-  const suffix = deployId.split('dd-')[1];
-  const privateRepoName = `engine-${suffix}-private`;
+  const privateRepoName = Underpost.repo.privateRepoFactory(deployId);
   const privateGitUri = `${process.env.GITHUB_USERNAME}/${privateRepoName}`;
   const privateRepoPath = `../${privateRepoName}`;
+  const cronDeployId = cronDeployIdResolve();
 
   if (!fs.existsSync(privateRepoPath)) {
     shellExec(`cd .. && underpost clone ${privateGitUri}`, { silent: true });
@@ -2991,17 +2976,21 @@ const syncPrivateConf = (deployId, extraPaths = []) => {
   fs.removeSync(confDest);
   fs.mkdirSync(confDest, { recursive: true });
   fs.copySync(`./engine-private/conf/${deployId}`, confDest);
-
+  // A checkout that declares no cron deploy has no `conf/<cron-id>` to mirror. Without this
+  // the path resolves to `conf/null` and the whole sync fails over an absent optional.
+  if (cronDeployId) fs.copySync(`./engine-private/conf/${cronDeployId}`, `${privateRepoPath}/conf/${cronDeployId}`);
+  fs.copySync(`./engine-private/deploy`, `${privateRepoPath}/deploy`);
   fs.removeSync(`${privateRepoPath}/replica`);
-  for (const payloadDir of ['replica', 'itc-scripts']) {
-    const srcDir = `./engine-private/${payloadDir}`;
-    if (!fs.existsSync(srcDir)) continue;
-    for (const entry of fs.readdirSync(srcDir))
-      if (entry.match(deployId)) fs.copySync(`${srcDir}/${entry}`, `${privateRepoPath}/${payloadDir}/${entry}`);
+  fs.removeSync(`${privateRepoPath}/logs`);
+  const replicaSrcDir = `./engine-private/replica`;
+  if (fs.existsSync(replicaSrcDir))
+    for (const entry of fs.readdirSync(replicaSrcDir))
+      if (entry.match(deployId)) fs.copySync(`${replicaSrcDir}/${entry}`, `${privateRepoPath}/replica/${entry}`);
+  for (const extraPath of extraPaths) {
+    fs.removeSync(`${privateRepoPath}/${extraPath}`);
+    fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
   }
 
-  for (const extraPath of extraPaths) fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
-
   shellExec(
     `cd ${privateRepoPath}` +
       ` && git add .` +
@@ -3031,31 +3020,111 @@ const syncDeployIdSources = (sourceMoves = []) => {
   return true;
 };
 
+const TEMPLATE_REPOSITORY_NAME = 'pwa-microservices-template';
+
+/**
+ * @method gitOriginRepositoryName
+ * @description Repository name a checkout's `origin` points at, without the `.git`
+ * suffix, or `null` when the path is not a work tree or declares no origin.
+ * @param {string} repoPath - Local repository path.
+ * @returns {string|null}
+ * @memberof ServerConfBuilder
+ */
+const gitOriginRepositoryName = (repoPath) => {
+  if (!fs.existsSync(`${repoPath}/.git`)) return null;
+  const url = shellExec(`cd ${repoPath} && git config --get remote.origin.url`, {
+    stdout: true,
+    silent: true,
+    disableLog: true,
+    silentOnError: true,
+  });
+  const name = typeof url === 'string' ? url.trim().split('/').pop() : '';
+  return name ? name.replace(/\.git$/, '') : null;
+};
+
+/**
+ * @method ensureTemplateCheckout
+ * @description Guarantees `toPath` is a checkout of the template repository, cloning it
+ * when it is missing or belongs to another repository.
+ *
+ * Publishing steps swap the checkout's `.git` for a product repository's history, so an
+ * assembly that trusted whatever `.git` it found would read another product's identity
+ * back into the base template `package.json`.
+ *
+ * @param {object} params
+ * @param {string} params.toPath - Template checkout path.
+ * @param {string} [params.githubUsername] - Owner of the template repository.
+ * @param {boolean} [params.noClone=false] - Fail instead of cloning a missing/foreign checkout.
+ * @returns {boolean} `true` when the checkout was restored.
+ * @memberof ServerConfBuilder
+ */
+const ensureTemplateCheckout = ({ toPath, githubUsername, noClone = false }) => {
+  const owner = githubUsername || 'underpostnet';
+  const repository = `${owner}/${TEMPLATE_REPOSITORY_NAME}`;
+  if (gitOriginRepositoryName(toPath) === TEMPLATE_REPOSITORY_NAME) return false;
+  if (noClone) throw new Error(`buildTemplate: ${toPath} is not a ${repository} checkout (--no-clone)`);
+  logger.warn('Restoring template checkout', { toPath, repository });
+
+  // Swap in the clone only once it is complete, so a failed one leaves the checkout as is.
+  const templatePath = dir.resolve(toPath);
+  const stagePath = fs.mkdtempSync(`${dir.dirname(templatePath)}/.${TEMPLATE_REPOSITORY_NAME}-`);
+  try {
+    shellExec(`cd ${stagePath} && node ${dir.resolve('./bin')} clone ${repository}`);
+    const clonePath = `${stagePath}/${TEMPLATE_REPOSITORY_NAME}`;
+    if (gitOriginRepositoryName(clonePath) !== TEMPLATE_REPOSITORY_NAME)
+      throw new Error(`buildTemplate: could not clone ${repository}`);
+    fs.removeSync(templatePath);
+    fs.moveSync(clonePath, templatePath);
+  } finally {
+    fs.removeSync(stagePath);
+  }
+  return true;
+};
+
+/**
+ * @method pruneTemplateWorkTree
+ * @description Empties the template checkout of everything a build reconstructs, so a
+ * source renamed or deleted in the engine — or a client bundle belonging to another
+ * deploy id — cannot survive from a previous run into the assembled output.
+ * @param {string} toPath - Template checkout path.
+ * @param {string[]} preservedEntries - Top level entries to keep (git history, installed modules).
+ * @returns {void}
+ * @memberof ServerConfBuilder
+ */
+const pruneTemplateWorkTree = (toPath, preservedEntries = []) => {
+  for (const entry of fs.readdirSync(toPath)) {
+    if (preservedEntries.includes(entry)) continue;
+    fs.removeSync(`${toPath}/${entry}`);
+  }
+};
+
 /**
  * Rebuilds the standalone `pwa-microservices-template` from scratch out of the current
  * engine source tree.
  *
- * Clones the template repo next to the engine when missing, otherwise resets it to a clean
- * pristine checkout, then syncs every engine-tracked file the template is allowed to carry
+ * Clones the template repo next to the engine when the checkout is missing or belongs to
+ * another repository, empties it so the result cannot inherit anything from a previous run,
+ * then syncs every engine-tracked file the template is allowed to carry
  * ({@link validateTemplatePath}), strips engine-only + product modules, restores the template's
  * own CI workflows + guest services, and rewrites `package.json` / `package-lock.json` / `README`
  * so the result is a standalone, installable project. Throws on failure; callers own exit codes.
  *
- * Product catalogs are read dynamically ({@link module:src/server/catalog} `loadProductCatalogs`),
+ * Product catalogs are read dynamically ({@link module:src/server/build/catalog.js} `loadProductCatalogs`),
  * so this stays decoupled from — and survives removal of — any product module.
  *
  * @method buildTemplate
  * @param {object} [options]
  * @param {string} [options.srcPath='./'] - Engine source root to sync from.
  * @param {string} [options.toPath='../pwa-microservices-template'] - Template output path.
+ * @param {boolean} [options.noClone=false] - Fail instead of cloning when the checkout is missing or foreign.
  * @returns {Promise<void>}
  * @memberof ServerConfBuilder
  */
-const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template' } = {}) => {
+const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template', noClone = false } = {}) => {
   const walk = (await import('ignore-walk')).default;
-  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } =
-    await import('../projects/underpost/catalog-underpost.js');
-  const { loadProductCatalogs } = await import('./catalog.js');
+  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_PRESERVED_ENTRIES, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } =
+    await import('../../projects/underpost/catalog-underpost.js');
+  const { loadProductCatalogs } = await import('../build/catalog.js');
   const githubUsername = process.env.GITHUB_USERNAME;
 
   logger.info('Build template', { srcPath, toPath });
@@ -3068,10 +3137,9 @@ const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-te
     )
   ).filter((p) => !p.startsWith('.git'));
 
-  fs.removeSync(`${githubUsername}/pwa-microservices-template`);
-  shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
-
+  ensureTemplateCheckout({ toPath, githubUsername, noClone });
   shellExec(`cd ${toPath} && git config core.filemode false`);
+  pruneTemplateWorkTree(toPath, TEMPLATE_PRESERVED_ENTRIES);
 
   for (const copyPath of sourceFiles) {
     if (copyPath === 'NaN') continue;
@@ -3180,7 +3248,8 @@ git add .`);
  * `engine-<idPart>`). A pod started with `underpost start --build --private-test-repo`
  * clones this repo, so work-in-progress engine source can be tested end to end
  * without touching the production source. Mirrors {@link updatePrivateTemplateRepo}
- * but per-deploy-id and against the test repo.
+ * but per-deploy-id and against the test repo, publishing from its own work tree
+ * (`<template parent>/engine-test-<idPart>`) so the template checkout keeps its identity.
  *
  * Assumes the deploy id template has already been assembled at the template path
  * (run `node bin/build <deployId>` first, or use `node bin/build <deployId> --update-private`).
@@ -3190,39 +3259,53 @@ git add .`);
  */
 const updatePrivateEngineTestRepo = async (deployId) => {
   const username = process.env.GITHUB_USERNAME || 'underpostnet';
-  const repoName = `engine-test-${deployId.split('-')[1]}`;
+  const repoName = Underpost.repo.engineRepoFactory(deployId, { test: true });
   const templatePath = '/home/dd/pwa-microservices-template';
   if (!fs.existsSync(templatePath))
     throw new Error(`updatePrivateEngineTestRepo: assemble the template first (node bin/build ${deployId})`);
 
-  // Detach the assembled working tree from any engine-build git history.
-  shellExec(`sudo rm -rf ${templatePath}/.git`);
-
   // Adopt the test repo's existing history when present (so the push is a delta);
   // otherwise publish a fresh history on first push.
-  shellExec(`cd /home/dd && sudo rm -rf ./${repoName}.git && underpost clone --bare ${username}/${repoName}`, {
+  const parentPath = dir.dirname(templatePath);
+  shellExec(`cd ${parentPath} && sudo rm -rf ./${repoName}.git && underpost clone --bare ${username}/${repoName}`, {
     silent: true,
     disableLog: true,
     silentOnError: true,
   });
-  if (fs.existsSync(`/home/dd/${repoName}.git`)) shellExec(`mv /home/dd/${repoName}.git ${templatePath}/.git`);
+
+  // Publishing from a work tree of its own leaves the template checkout its own git
+  // history, and copying that tree from 0 keeps a stale file out of the published one.
+  const publishPath = `${parentPath}/${repoName}`;
+  shellExec(`sudo rm -rf ${publishPath}`);
+  fs.copySync(templatePath, publishPath, {
+    filter: (src) => {
+      const entries = dir.relative(templatePath, src).split(dir.sep);
+      return !entries.includes('.git') && !entries.includes('node_modules');
+    },
+  });
+  if (fs.existsSync(`${parentPath}/${repoName}.git`)) shellExec(`mv ${parentPath}/${repoName}.git ${publishPath}/.git`);
 
   // `git init` converts the moved bare repo into a normal work-tree repo (bare
   // clones have no work tree, so `git add` would fail), and bootstraps a fresh
   // repo on first publish. Idempotent — mirrors updatePrivateTemplateRepo.
-  shellExec(`cd ${templatePath}
+  shellExec(`cd ${publishPath}
 git init
 git config user.name '${username}'
 git config user.email 'development@underpost.net'
-git add .`);
+git add -A .`);
 
-  const hasChanges = shellExec(`node bin cmt ${templatePath} --has-changes`, {
+  // The bundled coverage report is a build output the artifact has to carry: force-added so a
+  // tree-level ignore rule can never silently drop it from the published source.
+  if (fs.existsSync(`${publishPath}/${COVERAGE_BUNDLE_DIRECTORY}`))
+    shellExec(`cd ${publishPath} && git add -A -f ${COVERAGE_BUNDLE_DIRECTORY}`);
+
+  const hasChanges = shellExec(`node bin cmt ${publishPath} --has-changes`, {
     stdout: true,
     silent: true,
     disableLog: true,
   }).trim();
   if (hasChanges === '1')
-    shellExec(`cd ${templatePath} && git commit -m 'Update ${repoName}' && underpost push . ${username}/${repoName}`);
+    shellExec(`cd ${publishPath} && git commit -m 'Update ${repoName}' && underpost push . ${username}/${repoName}`);
   else logger.info('No changes to publish', { repoName });
 };
 
@@ -3243,12 +3326,15 @@ git add .`);
  * instance runs — `/etc/hosts` is written in one pass for every host the
  * gateway will serve.
  * @param {Array<string>} deployList - Deploy ids being brought up.
- * @param {string} [instanceList] - `+`-separated instance/template ids.
+ * @param {string} [instanceList] - Comma-separated instance/template ids, as `--instance-id` takes them.
  * @returns {{ byDeployId: Object<string,{ids: Array<string>, hosts: Array<string>}>, unmatched: Array<string> }}
  *   Per-deploy selection, and the requested ids no deploy declares.
  */
 const clusterInstancesFactory = (deployList = [], instanceList = '') => {
-  const requested = `${instanceList || ''}`.split('+').filter((id) => id.trim());
+  const requested = `${instanceList || ''}`
+    .split(',')
+    .map((id) => id.trim())
+    .filter(Boolean);
   const byDeployId = Object.fromEntries(
     deployList.map((deployId) => {
       const confPath = `./engine-private/conf/${deployId}/conf.instances.json`;
@@ -3273,6 +3359,10 @@ const clusterInstancesFactory = (deployList = [], instanceList = '') => {
 };
 
 export {
+  cleanDeployEnvFiles,
+  deployEnvFilePath,
+  deployEnvNamesFactory,
+  instanceEnvFilePath,
   Config,
   loadConf,
   loadConfInstances,
@@ -3292,25 +3382,19 @@ export {
   addWsConf,
   buildWsSrc,
   cloneSrcComponents,
-  buildProxyRouter,
   getDataDeploy,
   validateTemplatePath,
   buildReplicaId,
   mergeFile,
   getPathsSSR,
-  buildKindPorts,
-  buildPortProxyRouter,
   splitFileFactory,
   generateSecurePassword,
   resolveReplicaCount,
-  pathPortAssignmentFactory,
-  deployRangePortFactory,
   awaitDeployMonitor,
   buildCliDoc,
   getInstanceContext,
   buildApiConf,
   buildClientStaticConf,
-  isDeployRunnerContext,
   isDevProxyContext,
   devProxyHostFactory,
   isTlsDevProxy,
@@ -3320,6 +3404,10 @@ export {
   loadConfServerJson,
   getConfFolder,
   getConfFilePath,
+  deployEnvContentFactory,
+  deployOciEnvFilePath,
+  ociEnvContentFactory,
+  OCI_ENV_SUFFIX,
   readConfJson,
   DEFAULT_DEPLOY_ID,
   clusterContextFactory,
@@ -3344,10 +3432,13 @@ export {
   trafficProbePathsFactory,
   hostIngressFactsFactory,
   curlStatusChainFactory,
+  publicIngressProbeFactory,
+  publicIngressUrlsFactory,
   hostRenderInstancesFactory,
   instanceTrafficPlanFactory,
   isTrafficServingFactory,
   nextTrafficFactory,
+  redeployPlanFactory,
   schedulableNodeFactory,
   stopPlanFactory,
   trafficFromRoutingInfoFactory,
@@ -3355,9 +3446,11 @@ export {
   resolveEnvScoped,
   sortInstancesByPath,
   waitForPort,
-  resolveDeployList,
   syncPrivateConf,
   syncDeployIdSources,
+  gitOriginRepositoryName,
+  ensureTemplateCheckout,
+  pruneTemplateWorkTree,
   buildTemplate,
   updatePrivateTemplateRepo,
   updatePrivateEngineTestRepo,