underpost 3.2.80 → 3.2.90

package/src/server/conf.js

@@ -18,9 +18,12 @@ import {
   timer,
 } 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 { shellExec } from './process.js';
+import { UNDERPOST_GATEWAY, statusPageAssetPathFactory } from './underpost-gateway.js';
 import { DefaultConf } from '../../conf.js';
 import splitFile from 'split-file';
 import Underpost from '../index.js';
@@ -1378,6 +1381,56 @@ const splitFileFactory = async (name, _path) => {
   return false;
 };
 
+/**
+ * @method resolveReplicaCount
+ * @description Normalizes a CLI `--replicas` value to a positive integer, falling back to the
+ * caller's default when unset or invalid. Deliberately does not clamp upward: a floor would
+ * silently override an explicit, lower request, which is what made `--replicas 2` deploy three
+ * MongoDB members. Single source of truth so every statefulset reads the flag the same way.
+ * @param {string|number} input - Raw `--replicas` value.
+ * @param {number} [fallback=1] - Count to use when input is absent or not a positive integer.
+ * @returns {number} Effective replica count.
+ * @memberof ServerConfBuilder
+ */
+const resolveReplicaCount = (input, fallback = 1) => {
+  const parsed = Number.parseInt(input, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+/**
+ * @method generateSecurePassword
+ * @description Generates a cryptographically secure password satisfying every validatePassword
+ * constraint (lowercase, uppercase, digit, special character). Backed by `crypto.randomBytes`,
+ * never `Math.random`, because these values become long-lived service credentials.
+ * @param {number} [length=16] - Password length; values below 8 are raised to 8.
+ * @returns {string} The generated password.
+ * @memberof ServerConfBuilder
+ */
+const generateSecurePassword = (length = 16) => {
+  const size = Math.max(8, length);
+  const lower = 'abcdefghijklmnopqrstuvwxyz';
+  const upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  const digits = '0123456789';
+  const special = '@#$%^&*()_+';
+  const all = lower + upper + digits + special;
+  const buf = crypto.randomBytes(size + 4);
+  // Guarantee at least one character from each required class
+  const chars = [
+    lower[buf[0] % lower.length],
+    upper[buf[1] % upper.length],
+    digits[buf[2] % digits.length],
+    special[buf[3] % special.length],
+  ];
+  for (let i = 4; i < size; i++) chars.push(all[buf[i] % all.length]);
+  // Fisher-Yates shuffle using an independent random buffer
+  const shuf = crypto.randomBytes(size);
+  for (let i = chars.length - 1; i > 0; i--) {
+    const j = shuf[i % shuf.length] % (i + 1);
+    [chars[i], chars[j]] = [chars[j], chars[i]];
+  }
+  return chars.join('');
+};
+
 /**
  * @method getNpmRootPath
  * @description Gets the npm root path.
@@ -1807,40 +1860,106 @@ const readConfInstances = (deployId) => {
 
 /**
  * @method loadInstanceTopology
- * @description Returns `{ default, variants }` describing the deploy's instance
- * variants, or `null` when the deploy is single-instance. The topology is
- * declared per instance entry (`entry.multiInstance.default` / `.variants`); all
- * multi-instance entries share the same variant set, so this returns it from the
- * first entry that declares one.
+ * @description Returns normalized variants describing the deploy's instance
+ * topology, or `null` when the deploy is single-instance. The root path is the
+ * default variant; no separate default code is declared.
  * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
- * @returns {?{default: string, variants: Array<object>}} The topology, or `null`.
+ * @returns {?{variants: Array<object>}} The topology, or `null`.
  * @memberof ServerConfBuilder
  */
 const loadInstanceTopology = (deployId) => {
   for (const entry of readConfInstances(deployId)) {
     const mi = entry.multiInstance;
     if (mi && Array.isArray(mi.variants) && mi.variants.length > 0)
-      return { default: mi.default || mi.variants[0].code, variants: mi.variants };
+      return normalizeInstanceTopology(mi, `${deployId}/${entry.id}`);
   }
   return null;
 };
 
 /**
- * @method resolveInstanceEnvValue
- * @description Resolves one declared env value. A plain string is used verbatim;
- * an object is treated as env-scoped (`{ development, production }`), matching the
- * convention already used by `lifecycle` / `readinessProbe` / `livenessProbe`.
- * Placeholders are substituted from the variant tokens.
- * @param {string|object} value - Declared value.
- * @param {string} env - `development` | `production`.
- * @param {Object<string,string>} tokens - Placeholder name → replacement.
- * @returns {?string} Resolved value, or `null` when the env has no entry.
+ * @method normalizeInstanceTopology
+ * @description Expands the compact `multiInstance.variants` path list into the
+ * descriptors used by deploy tooling. `/` is always the default and keeps the
+ * template workload id. `/FOREST` produces code `FOREST`, slug `/forest`, and
+ * path `/FOREST`. A missing root entry is prepended automatically.
+ * @param {{variants?: Array<string>}} spec - Multi-instance specification.
+ * @param {string} [context] - Configuration location used in validation errors.
+ * @returns {{variants: Array<{code:string,slug:string,path:string,isDefault:boolean}>}}
  * @memberof ServerConfBuilder
  */
-const resolveInstanceEnvValue = (value, env, tokens) => {
-  const scoped = value && typeof value === 'object' && !Array.isArray(value) ? value[env] : value;
-  if (scoped === undefined || scoped === null) return null;
-  return `${scoped}`.replace(/\{\{(\w+)\}\}/g, (match, token) => (token in tokens ? tokens[token] : match));
+const normalizeInstanceTopology = (spec, context = 'multiInstance') => {
+  const declaredPaths = spec?.variants;
+  if (!Array.isArray(declaredPaths) || declaredPaths.length === 0) return { variants: [] };
+  if (declaredPaths.some((path) => typeof path !== 'string'))
+    throw new Error(`${context}: multiInstance.variants must contain only path strings`);
+  if (new Set(declaredPaths).size !== declaredPaths.length)
+    throw new Error(`${context}: multiInstance.variants contains a duplicate path`);
+  const paths = ['/', ...declaredPaths.filter((path) => path !== '/')];
+
+  const variants = paths.map((path) => {
+    if (path !== '/' && !/^\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(path))
+      throw new Error(`${context}: invalid instance variant path "${path}"`);
+    const code = path.slice(1);
+    return { code, slug: path === '/' ? '' : path.toLowerCase(), path, isDefault: path === '/' };
+  });
+
+  const seen = new Set();
+  for (const variant of variants) {
+    if (seen.has(variant.slug)) throw new Error(`${context}: duplicate instance variant "${variant.path}"`);
+    seen.add(variant.slug);
+  }
+  return { variants };
+};
+
+/**
+ * @method dispatchBuildInstanceEnv
+ * @description Applies an optional deploy-specific env builder to a canonical
+ * env object. Generic topology code never knows project env key names; callers
+ * register builders by deploy id. The runner-owned container id is applied last.
+ * @param {object} options - Dispatch context.
+ * @param {string} options.deployId - Deployment id used to select a builder.
+ * @param {object} options.instance - Expanded instance descriptor.
+ * @param {string} options.environment - development or production.
+ * @param {Object<string,string>} options.baseEnv - Parsed canonical env file.
+ * @param {string} options.containerDeployId - Runner-derived deployment id.
+ * @param {Object<string,Function>} [options.builders] - Deploy id to env builder registry.
+ * @returns {Object<string,string>} Complete materialized env object.
+ * @memberof ServerConfBuilder
+ */
+const dispatchBuildInstanceEnv = ({
+  deployId,
+  instance,
+  environment,
+  baseEnv = {},
+  containerDeployId,
+  builders = {},
+}) => {
+  const builder = builders[deployId];
+  const env = builder ? builder({ deployId, instance, environment, env: { ...baseEnv } }) : { ...baseEnv };
+  if (!env || typeof env !== 'object' || Array.isArray(env))
+    throw new TypeError(`dispatchBuildInstanceEnv: builder for "${deployId}" must return an env object`);
+  return { ...env, CONTAINER_DEPLOY_ID: containerDeployId };
+};
+
+/**
+ * Loads a deploy project's optional instance env builder by convention.
+ * `dd-cyberia` resolves to `src/projects/cyberia/instance-data.js`, whose
+ * public integration export is `buildInstanceEnv`. Missing modules mean the
+ * canonical env is copied unchanged; malformed exports fail explicitly.
+ * @param {string} deployId - Deployment id in `dd-<project>` form.
+ * @returns {Promise<Function|null>} Project env builder, when provided.
+ * @memberof ServerConfBuilder
+ */
+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);
+  if (!fs.existsSync(moduleUrl)) return null;
+  const projectModule = await import(moduleUrl.href);
+  if (projectModule.buildInstanceEnv === undefined) return null;
+  if (typeof projectModule.buildInstanceEnv !== 'function')
+    throw new TypeError(`${moduleUrl.pathname}: buildInstanceEnv must be a function`);
+  return projectModule.buildInstanceEnv;
 };
 
 /**
@@ -1851,67 +1970,46 @@ const resolveInstanceEnvValue = (value, env, tokens) => {
  * A template entry is never deployed as-is once variants exist: each variant
  * produces its own entry whose id, env file path, volume mount and
  * container-status strings are derived by replacing the template id token
- * throughout. The variant whose `slug` is empty keeps the template id verbatim,
- * so pre-existing deployments, PVCs and env directories survive the move to
- * multi-instance untouched.
- *
- * Nothing here is application-specific: the variant set (`default` + `variants`),
- * which env keys an instance needs (`env`), and prefix-stripping (`stripPathPrefix`)
- * are all declared per entry under `entry.multiInstance`. Env values may use the
- * `{{code}}`, `{{slug}}`, `{{path}}`, `{{id}}` and `{{default}}` placeholders and
- * may be env-scoped objects.
- *
- * Every expanded entry carries three extra fields consumed by the deploy runners:
- * `instanceCode` (the variant this instance serves), `templateId` (so targeting
- * the template id acts on the whole family) and `instanceEnv` (the resolved env
- * keys to write, keyed by environment: `{ development, production }`, so a build
- * in either mode can emit a complete env directory).
+ * throughout. The `/` variant keeps the template id verbatim, so pre-existing
+ * deployments, PVCs and env directories survive multi-instance expansion.
+ *
+ * Nothing here is application-specific: variants preserve their public path
+ * through the ingress and the runtime owns that base-path contract.
+ * Project-specific env behavior is delegated through
+ * {@link dispatchBuildInstanceEnv} rather than encoded in topology configuration.
+ *
+ * Every expanded entry carries normalized metadata consumed by deploy runners:
+ * `instanceCode`, `instanceSlug`, `isDefaultInstance`, and `templateId`.
  *
  * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
  * @returns {Array<object>} Expanded instance entries.
  * @memberof ServerConfBuilder
  */
-const INSTANCE_ENVS = ['development', 'production'];
-
 const loadConfInstances = (deployId) => {
   const expanded = [];
   for (const entry of readConfInstances(deployId)) {
     const spec = entry.multiInstance;
-    const variants = spec?.variants;
-    if (!Array.isArray(variants) || 0 === variants.length) {
-      expanded.push(entry);
+    if (!Array.isArray(spec?.variants) || spec.variants.length === 0) {
+      expanded.push(entry.path ? entry : { ...entry, path: '/' });
       continue;
     }
+    if (Object.hasOwn(spec, 'env'))
+      throw new Error(
+        `loadConfInstances: ${deployId}/${entry.id} uses removed multiInstance.env; ` +
+          'move project-specific env logic to a dispatch env builder',
+      );
+    const topology = normalizeInstanceTopology(spec, `${deployId}/${entry.id}`);
+    const variants = topology.variants;
     for (const variant of variants) {
-      const id = variant.slug ? `${entry.id}-${variant.slug}` : entry.id;
-      const instance = variant.slug ? deepReplaceToken(entry, entry.id, id) : JSON.parse(JSON.stringify(entry));
+      const id = variant.isDefault ? entry.id : `${entry.id}-${variant.slug.slice(1)}`;
+      const instance = variant.isDefault ? JSON.parse(JSON.stringify(entry)) : deepReplaceToken(entry, entry.id, id);
       delete instance.multiInstance;
       instance.id = id;
       instance.path = variant.path;
       instance.instanceCode = variant.code;
+      instance.instanceSlug = variant.slug;
+      instance.isDefaultInstance = variant.isDefault;
       instance.templateId = entry.id;
-
-      const tokens = {
-        code: variant.code,
-        slug: variant.slug || '',
-        path: variant.path,
-        id,
-        default: spec.default || '',
-      };
-      // Resolve the declared env keys for both environments so a build in either
-      // mode writes a complete env directory (development.env + production.env).
-      instance.instanceEnv = Object.fromEntries(INSTANCE_ENVS.map((e) => [e, {}]));
-      for (const [key, value] of Object.entries(spec.env || {}))
-        for (const e of INSTANCE_ENVS) {
-          const resolved = resolveInstanceEnvValue(value, e, tokens);
-          if (resolved !== null) instance.instanceEnv[e][key] = resolved;
-        }
-
-      // A backend that serves its routes at the root knows nothing about the
-      // variant prefix — it is selected by env instead. Strip the prefix at the
-      // proxy so the runtime stays instance-agnostic.
-      if (spec.stripPathPrefix && variant.path !== '/')
-        instance.pathRewritePolicy = [{ prefix: variant.path, replacement: '/' }];
       expanded.push(instance);
     }
   }
@@ -1931,13 +2029,952 @@ const loadConfInstances = (deployId) => {
 const selectConfInstances = (instances, id) =>
   instances.filter((instance) => instance.id === id || instance.templateId === id);
 
+/**
+ * @method resolveEnvScoped
+ * @description Resolves a conf value that may be declared either shared or
+ * env-scoped. An instance block is written as `{ ...spec }` when both
+ * environments share it and as `{ development: {...}, production: {...} }` when
+ * they do not; both shapes reach the manifest factories, which expect the
+ * resolved one.
+ * @param {object|undefined} value - Shared or env-scoped block.
+ * @param {string} env - `development` | `production`.
+ * @returns {object|undefined} The block for `env`, or the value unchanged when it is shared.
+ * @memberof ServerConfBuilder
+ */
+const resolveEnvScoped = (value, env) => (value && (value.development || value.production) ? value[env] : value);
+
+/**
+ * @method instancePortFactory
+ * @description The port an instance is reached on for an environment.
+ * Development prefers the instance's debug port when it declares one, so a
+ * local runtime can expose a debugger without the production port moving.
+ * @param {object} instance - Expanded instance entry.
+ * @param {string} env - `development` | `production`.
+ * @param {boolean} [container] - Resolve the container-side port (`toPort`) instead of the proxied one (`fromPort`).
+ * @returns {number|undefined} The effective port.
+ * @memberof ServerConfBuilder
+ */
+const instancePortFactory = ({ instance, env, container = false }) => {
+  const [port, debugPort] = container
+    ? [instance.toPort, instance.toDebugPort]
+    : [instance.fromPort, instance.fromDebugPort];
+  return env === 'development' && debugPort ? debugPort : port;
+};
+
+/**
+ * @method sortInstancesByPath
+ * @description Orders instances longest sub-path first, so a specific instance
+ * path (`/FOREST`) is never shadowed by the default instance's catch-all (`/`).
+ * @param {Array<object>} instances - Expanded instance entries.
+ * @returns {Array<object>} A new ordered array.
+ * @memberof ServerConfBuilder
+ */
+const sortInstancesByPath = (instances) =>
+  [...instances].sort((a, b) => (b.path || '/').length - (a.path || '/').length);
+
+/**
+ * @method deployHostsFactory
+ * @description Every hostname a deploy terminates: the ones its `conf.server.json`
+ * serves directly, plus the ones its `conf.instances.json` instances serve.
+ *
+ * Both sets reach the browser through the one Gateway the deploy owns, so both
+ * have to appear in its listener's certificate list and in the `/etc/hosts` pass
+ * — an instance host missing from either is unreachable even though its workload
+ * and route are correct.
+ *
+ * Every declared hostname is returned, not just the ones being deployed right
+ * now: the Gateway is per deploy, not per run, and a certificate reference it
+ * carries for a hostname the environment never provisioned is unresolvable —
+ * which costs the listener, and with it every other hostname on it.
+ * @param {string} deployId - Deployment identifier.
+ * @returns {Array<string>} Unique hostnames, deploy hosts first.
+ * @memberof ServerConfBuilder
+ */
+const deployHostsFactory = (deployId) => {
+  const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+  const confInstancesPath = `./engine-private/conf/${deployId}/conf.instances.json`;
+  const serverHosts = fs.existsSync(confServerPath) ? Object.keys(loadConfServerJson(confServerPath)) : [];
+  const instanceHosts = fs.existsSync(confInstancesPath)
+    ? loadConfInstances(deployId).map((instance) => instance.host)
+    : [];
+  return [...new Set([...serverHosts, ...instanceHosts].filter(Boolean))];
+};
+
+/**
+ * @method instanceStatusPageDeployIdFactory
+ * @description Status page documents are identical across a family's variants,
+ * so the resources holding them are named after the template instance and
+ * shared by every variant route.
+ * @param {string} deployId - Parent deployment identifier.
+ * @param {object} instance - Expanded instance entry.
+ * @returns {string} Family-scoped deploy id owning the status page resources.
+ * @memberof ServerConfBuilder
+ */
+const instanceStatusPageDeployIdFactory = (deployId, instance) => `${deployId}-${instance.templateId || instance.id}`;
+
+/**
+ * @method instanceProjectPathFactory
+ * @description Where an instance's own project sits in this checkout. A
+ * `customStatusPages` entry declares `hostPath` relative to that project
+ * (`./public/404/index.html`), not to the engine root, because the document is
+ * built and versioned by the project the instance runs.
+ *
+ * The directory is the repository's own name — the same name `underpost clone`
+ * checks it out under — falling back to the runtime and then the instance id.
+ * @param {object} instance - Expanded instance entry.
+ * @returns {string} Project root, relative to the engine root.
+ * @memberof ServerConfBuilder
+ */
+const instanceProjectPathFactory = (instance) =>
+  `./${`${instance?.metadata?.repository || instance?.runtime || instance?.id || ''}`.split('/').pop()}`;
+
+/**
+ * @method instanceStatusPageEntriesFactory
+ * @description Resolves every `customStatusPages` entry an instance declares
+ * into the document to copy and the place under the static root to copy it to.
+ *
+ * Single source of truth for the two sides that must agree exactly: the
+ * destination comes from the same {@link UnderpostGateway.statusPageAssetPathFactory}
+ * the HTTPRoute rewrites to, so a variant's page lands where that variant's rule
+ * points — `/FOREST/404` at `<host>/FOREST/status-pages/404/index.html`, and the
+ * default variant at `<host>/root/status-pages/404/index.html`.
+ * @param {Array<object>} instances - Expanded instance entries.
+ * @param {string} [projectPath] - Project root override; omit to derive one per instance.
+ * @returns {Array<{host: string, path: string, status: string, assetPath: string, sourcePath: string}>}
+ *   One entry per declared page, skipping entries missing a status or a source.
+ * @memberof ServerConfBuilder
+ */
+const instanceStatusPageEntriesFactory = ({ instances = [], projectPath }) =>
+  instances.flatMap((instance) =>
+    (instance.customStatusPages || [])
+      .filter((page) => page?.status && page?.hostPath)
+      .map((page) => ({
+        host: instance.host,
+        path: instance.path,
+        status: `${page.status}`,
+        assetPath: statusPageAssetPathFactory({ host: instance.host, path: instance.path, status: page.status })
+          .assetPath,
+        sourcePath: dir.normalize(`${projectPath || instanceProjectPathFactory(instance)}/${page.hostPath}`),
+      })),
+  );
+
+/**
+ * @method nextTrafficFactory
+ * @description The colour a promote routes to next.
+ *
+ * The single definition of the blue/green flip. An explicit request wins; with no
+ * colour live yet the canonical first colour is `blue`.
+ * @param {string} [liveTraffic] - Colour currently routed, or empty when none is.
+ * @param {string} [requestedTraffic] - Explicitly requested colour, if any.
+ * @returns {string} `blue` or `green`.
+ * @memberof ServerConfBuilder
+ */
+const nextTrafficFactory = (liveTraffic = '', requestedTraffic = '') =>
+  requestedTraffic === 'blue' || requestedTraffic === 'green'
+    ? requestedTraffic
+    : liveTraffic === 'blue'
+      ? 'green'
+      : 'blue';
+
+/**
+ * @method schedulableNodeFactory
+ * @description Narrows a chosen node name to one the cluster actually has.
+ *
+ * Node defaults are guessed from the environment when no cluster flag is given —
+ * `development` implies a kind cluster and therefore `kind-worker`. That guess is
+ * wrong on a `--dev` kubeadm cluster, and for a `hostNetwork` listener pinned by
+ * `nodeSelector` it is fatal rather than merely suboptimal: nothing schedules,
+ * and the name persists in the live object so every later run inherits it.
+ *
+ * A control-plane node is the last resort, not the first: on a multi-node cluster
+ * the public listener belongs on a worker. With no node list to check against the
+ * caller's choice is returned untouched — an unreadable cluster is not evidence
+ * the name is wrong.
+ * @param {Array<object>} [nodes] - Rows from `kubectl get nodes` (NAME, STATUS, ROLES).
+ * @param {string} [node] - The chosen node name.
+ * @returns {{node: string, corrected: boolean}} The name to use, and whether it had to change.
+ * @memberof ServerConfBuilder
+ */
+const schedulableNodeFactory = ({ nodes = [], node = '' }) => {
+  const named = nodes.filter((entry) => entry?.NAME);
+  if (named.length === 0) return { node, corrected: false };
+  if (node && named.some((entry) => entry.NAME === node)) return { node, corrected: false };
+  // STATUS can be a comma-joined list (e.g. "Ready,SchedulingDisabled").
+  const ready = named.filter((entry) => `${entry.STATUS || ''}`.split(',').includes('Ready'));
+  const pool = ready.length > 0 ? ready : named;
+  const worker = pool.find((entry) => !`${entry.ROLES || ''}`.includes('control-plane'));
+  return { node: (worker || pool[0]).NAME, corrected: true };
+};
+
+/**
+ * @method stopPlanFactory
+ * @description Resolves which colour-suffixed Deployments a stop should remove.
+ *
+ * Four ways to name them, in precedence order:
+ *
+ * 1. A literal comma path names the Deployments outright and every flag is
+ *    ignored — the caller already knows the exact object, so nothing is derived
+ *    and nothing else can be caught by accident.
+ * 2. `deployId` alone selects that deploy's PWA workload.
+ * 3. `deployId` with `instanceId` adds every custom instance of each id; a
+ *    template id expands to its whole variant family, since each variant is its
+ *    own Deployment.
+ * 4. `instanceId` without `deployId` is refused: an instance id is only unique
+ *    inside a deploy, so acting on it alone would be a guess.
+ *
+ * Colour selection is separate: `traffic` names the colours explicitly (a comma
+ * list, so `blue,green` stops both), and without it each target resolves to the
+ * blue/green partner of whatever it is currently serving — the colour that is by
+ * definition not carrying traffic.
+ * @param {string} [path] - Literal comma-separated Deployment names.
+ * @param {string} [deployId] - Deploy id whose workload and instances are targeted.
+ * @param {string} [instanceId] - Comma-separated instance or template ids.
+ * @param {string} [traffic] - Comma-separated colours; empty means the inactive one.
+ * @param {string} [env] - `development` | `production`.
+ * @param {Function} [instancesFor] - `(instanceId) => Array<object>` expanded instances.
+ * @param {Function} [liveTrafficOf] - `(target) => 'blue' | 'green' | '' | null`.
+ * @returns {{deployments: Array<object>, error: string|null}} The plan, or why there isn't one.
+ * @memberof ServerConfBuilder
+ */
+const stopPlanFactory = ({
+  path = '',
+  deployId = '',
+  instanceId = '',
+  traffic = '',
+  env = '',
+  instancesFor = () => [],
+  liveTrafficOf = () => '',
+}) => {
+  const list = (value) =>
+    `${value || ''}`
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+  const literal = list(path);
+  if (literal.length > 0)
+    return {
+      deployments: literal.map((deployment) => ({ deployment, kind: 'literal', id: deployment, host: '', colour: '' })),
+      error: null,
+    };
+
+  const instanceIds = list(instanceId);
+  if (!deployId)
+    return {
+      deployments: [],
+      error:
+        instanceIds.length > 0
+          ? '--instance-id requires --deploy-id: an instance id is only unique inside a deploy'
+          : 'nothing to stop: pass a literal deployment path, or --deploy-id',
+    };
+
+  const requestedRaw = list(traffic);
+  const requested = requestedRaw.filter((colour) => colour === 'blue' || colour === 'green');
+  if (requestedRaw.length > 0 && requested.length === 0)
+    return { deployments: [], error: `--traffic accepts blue and/or green, got: ${requestedRaw.join(',')}` };
+
+  const targets = [{ id: deployId, host: '', kind: 'pwa' }];
+  for (const id of instanceIds)
+    for (const instance of instancesFor(id))
+      targets.push({ id: `${deployId}-${instance.id}`, host: instance.host || '', kind: 'instance' });
+
+  const deployments = [];
+  const seen = new Set();
+  for (const target of targets)
+    for (const colour of requested.length > 0 ? requested : [nextTrafficFactory(liveTrafficOf(target))]) {
+      const deployment = `${target.id}-${env}-${colour}`;
+      if (seen.has(deployment)) continue;
+      seen.add(deployment);
+      deployments.push({ ...target, colour, deployment });
+    }
+  return { deployments, error: null };
+};
+
+/**
+ * @method trafficFromRoutingInfoFactory
+ * @description Reads a deployment's live colour out of the routing text that
+ * carries it.
+ *
+ * Legacy stacks name the backend Service `<deployId>-<env>-<colour>-service`;
+ * the stable traffic Service names the same value in `spec.selector.app` without
+ * the `-service` suffix. The colour therefore reads the same way during and
+ * after migration. Kept pure and separate
+ * from the read so one host's routing text can be matched against several
+ * deployments and environments without fetching it again.
+ *
+ * With `env` given the match is anchored on the full `<deployId>-<env>-` prefix:
+ * essential on a shared multi-instance host, where one object holds several
+ * variants' routes on possibly different colours, and where an unanchored match
+ * would return a sibling's answer. `dd-cyberia-mmo-server` never matches
+ * `dd-cyberia-mmo-server-forest` this way.
+ * @param {string} [info] - Routing text (route object YAML and/or Nginx block).
+ * @param {string} deployId - Deployment identifier the colour is wanted for.
+ * @param {string} [env] - `development` | `production`; omitted falls back to a whole-text match.
+ * @returns {string|null} `blue`, `green`, or null when the text names neither.
+ * @memberof ServerConfBuilder
+ */
+const trafficFromRoutingInfoFactory = ({ info = '', deployId = '', env = '' }) => {
+  if (!`${info}`.trim()) return null;
+  if (env) {
+    const escaped = `${deployId}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = `${info}`.match(new RegExp(`${escaped}-${env}-(blue|green)(?:-service)?(?:\\s|$)`));
+    return match ? match[1] : null;
+  }
+  return `${info}`.match('blue') ? 'blue' : `${info}`.match('green') ? 'green' : null;
+};
+
+/**
+ * @method trafficProbePathsFactory
+ * @description The literal paths a conf.server.json route should be probed on,
+ * matching the `replicas`/`singleReplica` convention `loadReplicas` expands for
+ * a real build (see push-bundle/pull-bundle): a `singleReplica` route is never
+ * itself served, so probing its canonical path always reads as unrouted; a
+ * plain `replicas` route serves the canonical path in addition to each replica.
+ * Read-only by design — a traffic report must not mutate conf.server.json as a
+ * side effect of being read, unlike `loadReplicas`.
+ * @param {object} [routeConf] - `confServer[host][path]` entry.
+ * @param {string} routePath - The canonical path key.
+ * @returns {Array<string>} Paths to probe for this route.
+ * @memberof ServerConfBuilder
+ */
+const trafficProbePathsFactory = (routeConf = {}, routePath) => {
+  const replicas = Array.isArray(routeConf.replicas) ? routeConf.replicas : [];
+  if (replicas.length === 0) return [routePath];
+  return routeConf.singleReplica ? replicas : [routePath, ...replicas];
+};
+
+/**
+ * @method deployTrafficEntriesFactory
+ * @description Every routable deployment a deploy id owns, of both kinds.
+ *
+ * The two kinds are named differently in the cluster and resolved from different
+ * conf files, which is exactly why a colour report has to build them together:
+ * the PWA workload is one Deployment per deploy id serving whatever hosts its
+ * `conf.server.json` declares, while each expanded custom instance is its own
+ * Deployment behind one host sub-path.
+ * @param {string} deployId - Deployment identifier.
+ * @param {string} env - `development` | `production`.
+ * @returns {Array<{kind: string, deployId: string, id: string, host: string, path: string, deployment: string}>} One entry per routable deployment.
+ * @memberof ServerConfBuilder
+ */
+const deployTrafficEntriesFactory = ({ deployId, env }) => {
+  const entries = [];
+  const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+  if (fs.existsSync(confServerPath)) {
+    const confServer = loadConfServerJson(confServerPath);
+    for (const host of Object.keys(confServer))
+      entries.push({
+        kind: 'pwa',
+        deployId,
+        id: deployId,
+        host,
+        path:
+          Object.keys(confServer[host])
+            .flatMap((routePath) => trafficProbePathsFactory(confServer[host][routePath], routePath))
+            .join(' ') || '/',
+        deployment: `${deployId}-${env}`,
+      });
+  }
+  if (fs.existsSync(`./engine-private/conf/${deployId}/conf.instances.json`))
+    for (const instance of loadConfInstances(deployId))
+      entries.push({
+        kind: 'instance',
+        deployId,
+        id: `${deployId}-${instance.id}`,
+        host: instance.host,
+        path: instance.path || '/',
+        deployment: `${deployId}-${instance.id}-${env}`,
+      });
+  return entries;
+};
+
+/**
+ * @method hostIngressFactsFactory
+ * @description What the cluster's routing objects say about each hostname: which
+ * kind describes it, whether it is served over TLS, and whether HTTP/3 is on.
+ *
+ * None of the three can be read from the route object alone. The kind is which
+ * object exists; TLS lives on the Gateway's listener (an HTTPRoute never carries
+ * it) or on an HTTPProxy's `virtualhost.tls`; and HTTP/3 is a `ClientTrafficPolicy`
+ * targeting that Gateway. So the answer is a correlation across four kinds, done
+ * once for the whole cluster rather than per row.
+ *
+ * A hostname described by both kinds is a leftover from switching stacks; the
+ * HTTPRoute wins, matching the precedence the shared ingress routes it with.
+ * @param {Array<object>} [httpRoutes] - HTTPRoute items.
+ * @param {Array<object>} [httpProxies] - HTTPProxy items.
+ * @param {Array<object>} [gateways] - Gateway items.
+ * @param {Array<object>} [clientTrafficPolicies] - ClientTrafficPolicy items.
+ * @returns {Object<string,{route: string, tls: boolean, http3: boolean}>} Facts by hostname.
+ * @memberof ServerConfBuilder
+ */
+const hostIngressFactsFactory = ({
+  httpRoutes = [],
+  httpProxies = [],
+  gateways = [],
+  clientTrafficPolicies = [],
+} = {}) => {
+  const tlsGateways = new Set(
+    gateways
+      .filter((gateway) =>
+        (gateway?.spec?.listeners || []).some((listener) => `${listener?.protocol}`.toUpperCase() === 'HTTPS'),
+      )
+      .map((gateway) => gateway?.metadata?.name)
+      .filter(Boolean),
+  );
+  // QUIC only exists where TLS does, so a policy naming a Gateway with no HTTPS
+  // listener describes nothing — the same reason the policy is emitted scoped to
+  // the HTTPS section in the first place.
+  const http3Gateways = new Set(
+    clientTrafficPolicies
+      .filter((policy) => policy?.spec?.http3 !== undefined)
+      .flatMap((policy) => [...(policy?.spec?.targetRefs || []), policy?.spec?.targetRef].filter(Boolean))
+      .map((ref) => ref?.name)
+      .filter((name) => name && tlsGateways.has(name)),
+  );
+
+  const facts = {};
+  for (const proxy of httpProxies) {
+    const host = proxy?.spec?.virtualhost?.fqdn;
+    if (!host) continue;
+    facts[host] = { route: 'HTTPProxy', tls: !!proxy?.spec?.virtualhost?.tls, http3: false };
+  }
+  for (const route of httpRoutes) {
+    const parents = (route?.spec?.parentRefs || []).map((ref) => ref?.name).filter(Boolean);
+    const tls = parents.some((name) => tlsGateways.has(name));
+    const http3 = parents.some((name) => http3Gateways.has(name));
+    for (const host of route?.spec?.hostnames || []) if (host) facts[host] = { route: 'HTTPRoute', tls, http3 };
+  }
+  return facts;
+};
+
+/**
+ * @method curlStatusChainFactory
+ * @description Extracts the response chain emitted by `curl -L -v -i -s`.
+ * Verbose response lines are authoritative because `-i` can duplicate the same
+ * headers on stdout. A write-out marker supplies the final code when curl did
+ * not emit a verbose response (and `000` when no HTTP response was received).
+ * CONNECT tunnel acknowledgements are transport setup, not host responses, and
+ * are deliberately excluded from the displayed chain.
+ * @param {string} [raw] - Combined curl stdout/stderr.
+ * @returns {Array<string>} Ordered three-digit response codes.
+ * @memberof ServerConfBuilder
+ */
+const curlStatusChainFactory = (raw = '') => {
+  const text = `${raw || ''}`;
+  const verbose = [...text.matchAll(/^< HTTP\/\S+\s+([0-9]{3})(?![^\n]*Connection established)/gim)].map(
+    (match) => match[1],
+  );
+  const headers = [...text.matchAll(/^HTTP\/\S+\s+([0-9]{3})(?![^\n]*Connection established)/gim)].map(
+    (match) => match[1],
+  );
+  const chain = verbose.length > 0 ? verbose : headers;
+  const finalCode = /UNDERPOST_CURL_FINAL=([0-9]{3})/.exec(text)?.[1] || '';
+  if (finalCode && finalCode !== '000' && chain[chain.length - 1] !== finalCode) chain.push(finalCode);
+  if (chain.length === 0) chain.push(finalCode || '000');
+  return chain;
+};
+
+/**
+ * @method trafficTableRowsFactory
+ * @description Resolves the live colour of each routable deployment, optionally
+ * narrowed to a set of hosts.
+ *
+ * Cluster lookups are injected so the shaping stays a pure resolution over the
+ * conf. An entry whose colour cannot be read is reported with an empty colour
+ * rather than dropped — "no route published" is the answer, not an absence.
+ * @param {Array<object>} [entries] - Entries from {@link ServerConfBuilder.deployTrafficEntriesFactory}.
+ * @param {Array<string>} [hosts] - Hosts to report on; empty reports every host.
+ * @param {Function} liveTrafficOf - `(entry) => 'blue' | 'green' | '' | null`.
+ * @param {Function} servesTraffic - `(entry, colour) => boolean`.
+ * @returns {Array<object>} Entries with `traffic` and `serving` resolved.
+ * @memberof ServerConfBuilder
+ */
+const trafficTableRowsFactory = ({
+  entries = [],
+  hosts = [],
+  liveTrafficOf = () => '',
+  servesTraffic = () => false,
+}) => {
+  const wanted = new Set(hosts.filter(Boolean));
+  return entries
+    .filter((entry) => wanted.size === 0 || wanted.has(entry.host))
+    .map((entry) => {
+      const traffic = liveTrafficOf(entry) || '';
+      return {
+        ...entry,
+        traffic,
+        serving: isTrafficServingFactory({
+          liveTraffic: traffic,
+          hasReadyEndpoints: (colour) => servesTraffic(entry, colour),
+        }),
+      };
+    });
+};
+
+/**
+ * @method hostRenderInstancesFactory
+ * @description The instances a shared host's routing must be rendered from.
+ *
+ * A host's Nginx server block and its HTTPRoute are single objects shared by
+ * every variant on that host, so both are rewritten whole on every promote.
+ * Rendering them from the declared set alone therefore deletes the routes of any
+ * variant that is still deployed but no longer declared — silently taking down a
+ * workload this deploy was never asked to touch.
+ *
+ * Each variant sub-path is its own deployment, so a variant loses its route only
+ * once its workload is actually gone. `preserved` carries the descriptors last
+ * published for this host; a declared entry always wins, since it is the current
+ * truth for that id.
+ * @param {Array<object>} [declared] - Instances the conf declares for this host.
+ * @param {Array<object>} [preserved] - Instances last published for this host.
+ * @param {Function} [isDeployed] - `(instance) => boolean`, true while its workload exists.
+ * @returns {Array<object>} Declared entries, plus still-deployed preserved ones.
+ * @memberof ServerConfBuilder
+ */
+const hostRenderInstancesFactory = ({ declared = [], preserved = [], isDeployed = () => false }) => {
+  const declaredIds = new Set(declared.map((instance) => instance.id));
+  return [
+    ...declared,
+    ...preserved.filter((instance) => instance?.id && !declaredIds.has(instance.id) && isDeployed(instance)),
+  ];
+};
+
+/**
+ * @method isTrafficServingFactory
+ * @description Whether a routed colour is actually carrying traffic.
+ *
+ * The one gate every no-backend fallback checkpoint is conditional on, shared by
+ * `run sync` and `run instance`. A colour is serving only when it is both routed
+ * and still has a ready endpoint: a route can name a colour whose workload is
+ * long gone, and taking a host offline to prove a fallback is only acceptable
+ * when nothing is serving it.
+ * @param {string} [liveTraffic] - Colour currently routed, or empty when none is.
+ * @param {Function} hasReadyEndpoints - `(colour) => boolean`.
+ * @returns {boolean} True when that colour is routed and reachable.
+ * @memberof ServerConfBuilder
+ */
+const isTrafficServingFactory = ({ liveTraffic = '', hasReadyEndpoints = () => false }) =>
+  !!liveTraffic && hasReadyEndpoints(liveTraffic);
+
+/**
+ * @method instanceTrafficPlanFactory
+ * @description Resolves, for each instance, the colour routed now and the colour
+ * to route next, and which instances are actually serving on the live one.
+ *
+ * `serving` is the precondition for the no-backend fallback checkpoint, which
+ * routes the edge at a colour that has no Deployment yet. That is correct on a
+ * first bring-up and an outage on a re-deploy, and a routed colour is only real
+ * traffic when it still has a ready endpoint — a route alone can name a colour
+ * whose workload is long gone.
+ *
+ * Cluster lookups are injected so this stays a pure resolution over the conf.
+ * @param {Array<object>} [instances] - Expanded instance entries.
+ * @param {string} [requestedTraffic] - Explicitly requested colour, if any.
+ * @param {Function} liveTrafficOf - `(instance) => 'blue' | 'green' | '' | null`.
+ * @param {Function} servesTraffic - `(instance, colour) => boolean`, true when that colour has a ready endpoint.
+ * @returns {{liveTrafficById: Object<string,string>, targetTrafficById: Object<string,string>, serving: Array<object>}} The plan.
+ * @memberof ServerConfBuilder
+ */
+const instanceTrafficPlanFactory = ({
+  instances = [],
+  requestedTraffic = '',
+  liveTrafficOf = () => '',
+  servesTraffic = () => false,
+}) => {
+  const liveTrafficById = {};
+  const targetTrafficById = {};
+  const serving = [];
+  for (const instance of instances) {
+    const liveTraffic = liveTrafficOf(instance) || '';
+    liveTrafficById[instance.id] = liveTraffic;
+    targetTrafficById[instance.id] = nextTrafficFactory(liveTraffic, requestedTraffic);
+    if (isTrafficServingFactory({ liveTraffic, hasReadyEndpoints: (colour) => servesTraffic(instance, colour) }))
+      serving.push(instance);
+  }
+  return { liveTrafficById, targetTrafficById, serving };
+};
+
+/**
+ * @method instanceInterceptStatusesFactory
+ * @description The statuses the gateway intercepts for one instance, and the
+ * context directory each is answered from.
+ *
+ * Driven entirely by what the instance declares: every `customStatusPages` entry
+ * answers its own status, and those declarations are also what upstream-failure
+ * codes fall back to — a variant whose workload is gone should show the same page
+ * as one that has no such route, because to the client they are the same thing.
+ * @param {object} instance - Expanded instance entry.
+ * @returns {Object<string,string>} Status code → context directory under the instance sub-path.
+ * @memberof ServerConfBuilder
+ */
+const instanceInterceptStatusesFactory = (instance) => {
+  const statuses = {};
+  for (const page of instance?.customStatusPages || []) {
+    if (!page?.status || !page?.hostPath) continue;
+    const context = `status-pages/${page.status}`;
+    statuses[page.status] = context;
+    // Custom instances do not have the PWA's `maintenanceDefault` SSR view.
+    // Their declared status document is therefore also the only useful answer
+    // while the binary is absent or still becoming Ready. Nginx preserves the
+    // original 502/503/504 code while substituting this document, so clients
+    // can distinguish an unavailable runtime from the instance's own 404.
+    for (const failureStatus of [502, 503, 504]) if (!statuses[failureStatus]) statuses[failureStatus] = context;
+  }
+  return statuses;
+};
+
+/**
+ * @method instanceProxyRoutesFactory
+ * @description Renders the Contour HTTPProxy route block for every instance
+ * sharing a host.
+ * @param {string} deployId - Parent deployment identifier.
+ * @param {Array<object>} instances - Expanded instance entries bound to one host.
+ * @param {string} env - `development` | `production`.
+ * @param {Object<string,string>} trafficById - Instance id → traffic colour.
+ * @returns {string} Concatenated route YAML.
+ * @memberof ServerConfBuilder
+ */
+const instanceProxyRoutesFactory = ({ deployId, instances, env, trafficById }) =>
+  sortInstancesByPath(instances)
+    .map((instance) =>
+      Underpost.deploy.deploymentYamlServiceFactory({
+        path: instance.path,
+        port: instancePortFactory({ instance, env }),
+        serviceId: Underpost.deploy.trafficServiceNameFactory({ deployId: `${deployId}-${instance.id}`, env }),
+        pathRewritePolicy: instance.pathRewritePolicy,
+      }),
+    )
+    .join('');
+
+/**
+ * @method instanceHttpRouteRulesFactory
+ * @description Renders the Gateway API rules for every instance sharing a host:
+ * the workload rule for each instance sub-path, plus the edge-served status page
+ * rules declared by that instance's `customStatusPages`.
+ *
+ * Variant paths are preserved by default, so the selected runtime receives the
+ * same URL that the client requested. An explicit generic `pathRewritePolicy`
+ * is still passed through for unrelated workloads that define one directly.
+ * @param {string} deployId - Parent deployment identifier.
+ * @param {Array<object>} instances - Expanded instance entries bound to one host.
+ * @param {string} env - `development` | `production`.
+ * @param {Object<string,string>} trafficById - Instance id → traffic colour.
+ * @param {object} [options] - Runner options (namespace, gateway/QUIC settings).
+ * @param {Array<string>} [servedStatuses] - Statuses whose document reached the static tree; undefined means all declared.
+ * @returns {string} Concatenated rule YAML.
+ * @memberof ServerConfBuilder
+ */
+const instanceHttpRouteRulesFactory = ({ deployId, instances, env, trafficById, options, servedStatuses }) => {
+  const { http3, altSvc } = Underpost.deploy.gatewayApiConfigFactory(options);
+  const sorted = sortInstancesByPath(instances);
+  // The `/` status fallback is only emitted when no workload claims the root
+  // path: two rules matching `/` would leave gateway precedence ambiguous.
+  const rootClaimed = sorted.some((instance) => (instance.path || '/') === '/');
+  let rules = '';
+  for (const [i, instance] of sorted.entries()) {
+    rules += Underpost.deploy.statusPageRouteRulesFactory({
+      deployId: instanceStatusPageDeployIdFactory(deployId, instance),
+      host: instance.host,
+      basePath: instance.path,
+      statusPages: instance.customStatusPages,
+      altSvc: http3 ? altSvc : undefined,
+      catchAll: !rootClaimed && i === sorted.length - 1,
+      servedStatuses,
+    });
+    // An instance that declares a status page is reached through the shared
+    // gateway, which proxies to its workload and intercepts the errors. One that
+    // declares none is routed straight there, so the extra hop only exists where
+    // it buys something. Any explicit generic `pathRewritePolicy` moves to the
+    // gateway with the workload route.
+    const intercepted = Object.keys(instanceInterceptStatusesFactory(instance)).length > 0;
+    rules += Underpost.deploy.httpRouteRuleFactory({
+      path: instance.path,
+      ...(intercepted
+        ? { serviceId: UNDERPOST_GATEWAY.serviceName, port: UNDERPOST_GATEWAY.port }
+        : {
+            port: instancePortFactory({ instance, env }),
+            serviceId: Underpost.deploy.trafficServiceNameFactory({ deployId: `${deployId}-${instance.id}`, env }),
+            pathRewritePolicy: instance.pathRewritePolicy,
+          }),
+      altSvc: http3 ? altSvc : undefined,
+    });
+  }
+  return rules;
+};
+
+/**
+ * @method clusterTypeFactory
+ * @description The cluster runtime a set of options selects, as the string every
+ * command line and volume context spells it.
+ * @param {object} [options] - Options carrying the cluster flags.
+ * @param {string} [defaultType] - Type when no flag is set; `kind` everywhere except workflows that never provision one.
+ * @returns {string} `k3s` | `kubeadm` | `kind`.
+ * @memberof ServerConfBuilder
+ */
+const clusterTypeFactory = (options = {}, defaultType = 'kind') =>
+  options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : defaultType;
+
+/**
+ * A row returned by {@link UnderpostKubectl.get}. Column names come from
+ * `kubectl get -o wide`; Services expose their port column as `PORT(S)`.
+ *
+ * @typedef {Object<string, string|undefined>} ExposeKubernetesResource
+ * @property {string} NAME - Kubernetes resource name.
+ */
+
+/**
+ * @method exposeTcpPortsFactory
+ * @description Extracts TCP Service ports from a parsed
+ * `kubectl get svc -o wide` row. NodePort suffixes are ignored, so
+ * `8080:32080/TCP` resolves to Service port `8080`.
+ * @param {ExposeKubernetesResource} resource - Parsed Kubernetes resource row.
+ * @returns {number[]} Positive TCP Service ports in the order reported by kubectl.
+ * @memberof ServerConfBuilder
+ */
+const exposeTcpPortsFactory = (resource) =>
+  `${resource?.['PORT(S)'] || ''}`
+    .split(',')
+    .filter((port) => port.includes('/TCP'))
+    .map((port) => parseInt(port.split(':')[0]))
+    .filter((port) => Number.isInteger(port) && port > 0);
+
+/**
+ * @method exposePathPartsFactory
+ * @description Parses a comma-separated expose runner path into safe literal
+ * Kubernetes name fragments. These are literal fragments, not regular
+ * expressions or shell input.
+ * @param {string} [path=''] - Comma-separated Service or Pod name fragments.
+ * @returns {string[]} Trimmed, non-empty literal resource-name fragments.
+ * @throws {Error} When no fragment is supplied or a fragment contains
+ * characters outside `[a-zA-Z0-9._-]`.
+ * @memberof ServerConfBuilder
+ */
+const exposePathPartsFactory = (path = '') => {
+  const parts = `${path}`
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) throw new Error('Expose requires a Service or Pod name in path');
+  if (parts.some((part) => !/^[a-zA-Z0-9._-]+$/.test(part)))
+    throw new Error(`Invalid Kubernetes resource name match: ${path}`);
+  return parts;
+};
+
+/**
+ * @method exposePartialMatchesFactory
+ * @description Selects every resource whose `NAME` contains any requested
+ * literal path fragment. Results follow path-fragment order, with an exact name
+ * before partial names in each group, then lexical name order. The input array
+ * is not mutated.
+ * @param {ExposeKubernetesResource[]} resources - Parsed Kubernetes resource rows.
+ * @param {string[]} pathParts - Literal name fragments from {@link exposePathPartsFactory}.
+ * @returns {ExposeKubernetesResource[]} Matching resource rows in deterministic order.
+ * @memberof ServerConfBuilder
+ */
+const exposePartialMatchesFactory = (resources, pathParts) =>
+  resources
+    .filter(({ NAME }) => pathParts.some((part) => `${NAME || ''}`.includes(part)))
+    .sort((a, b) => {
+      const pathIndexA = pathParts.findIndex((part) => `${a.NAME || ''}`.includes(part));
+      const pathIndexB = pathParts.findIndex((part) => `${b.NAME || ''}`.includes(part));
+      const exactA = a.NAME === pathParts[pathIndexA] ? 0 : 1;
+      const exactB = b.NAME === pathParts[pathIndexB] ? 0 : 1;
+      return pathIndexA - pathIndexB || exactA - exactB || `${a.NAME}`.localeCompare(`${b.NAME}`);
+    });
+
+/**
+ * @method exposePortListFactory
+ * @description Parses and validates a comma-separated CLI port list.
+ * @param {string|number} [value=''] - Comma-separated port values.
+ * @param {string} [optionName='ports'] - Option name used in validation errors.
+ * @returns {number[]} Ordered TCP ports, preserving their CLI indices.
+ * @throws {Error} When an item is empty, non-integer, or outside `1..65535`.
+ * @memberof ServerConfBuilder
+ */
+const exposePortListFactory = (value = '', optionName = 'ports') => {
+  if (value === '' || value === undefined || value === null) return [];
+  const values = `${value}`.split(',').map((port) => port.trim());
+  if (values.some((port) => port === '')) throw new Error(`Invalid ${optionName}: ${value}`);
+  const ports = values.map(Number);
+  if (ports.some((port) => !Number.isInteger(port) || port < 1 || port > 65535))
+    throw new Error(`Invalid ${optionName}: ${value}`);
+  return ports;
+};
+
+/**
+ * A validated Kubernetes port-forward mapping.
+ *
+ * @typedef {Object} ExposePortMapping
+ * @property {string} kindType - Kubernetes resource kind (`svc` or `pod`).
+ * @property {string} name - Kubernetes resource name.
+ * @property {number} localPort - Host-side listening port.
+ * @property {number} remotePort - Service or container-side destination port.
+ */
+
+/**
+ * @method exposePortPlanFactory
+ * @description Builds a complete, collision-free port-forward plan. With more
+ * than one matched resource, container and host port lists map by resource
+ * index. With one resource, list items map pairwise to multiple ports.
+ * @param {object} options - Port planning options.
+ * @param {ExposeKubernetesResource[]} options.resources - Ordered matched resources.
+ * @param {string} options.kindType - Kubernetes resource kind (`svc` or `pod`).
+ * @param {number[]} [options.containerPorts=[]] - Explicit destination ports.
+ * @param {number[]} [options.hostPorts=[]] - Explicit host listening ports.
+ * @param {function(ExposeKubernetesResource): number[]} [options.portsOf=exposeTcpPortsFactory] - Declared-port resolver.
+ * @returns {ExposePortMapping[]} Complete port-forward mappings.
+ * @throws {Error} When list cardinality cannot map by resource/port index, no
+ * destination port exists, an explicit host port repeats, or an automatic port
+ * cannot fit inside `1..65535`.
+ * @memberof ServerConfBuilder
+ */
+const exposePortPlanFactory = ({
+  resources,
+  kindType,
+  containerPorts = [],
+  hostPorts = [],
+  portsOf = exposeTcpPortsFactory,
+}) => {
+  const resourceCount = resources.length;
+  const multipleResources = resourceCount > 1;
+  if (multipleResources && containerPorts.length > 0 && containerPorts.length !== resourceCount)
+    throw new Error(`--expose-container-ports requires ${resourceCount} ports for ${resourceCount} resources`);
+  if (multipleResources && hostPorts.length > 0 && hostPorts.length !== resourceCount)
+    throw new Error(`--expose-host-ports requires ${resourceCount} ports for ${resourceCount} resources`);
+
+  const portGroups = resources.map((resource, resourceIndex) => {
+    const declaredPorts = [...new Set(portsOf(resource))];
+    let remotePorts = [];
+    if (containerPorts.length > 0) {
+      remotePorts = multipleResources ? [containerPorts[resourceIndex]] : [...containerPorts];
+    } else if (hostPorts.length > 0 && !multipleResources) {
+      remotePorts = hostPorts.map((hp) => (declaredPorts.includes(hp) ? hp : null)).filter(Boolean);
+      if (remotePorts.length !== hostPorts.length) {
+        remotePorts = declaredPorts.slice(0, hostPorts.length);
+      }
+    } else {
+      remotePorts = declaredPorts;
+    }
+    if (remotePorts.length === 0)
+      throw new Error(`No declared TCP port for ${kindType}/${resource.NAME}; pass --expose-container-ports <ports>`);
+    const localPorts = hostPorts.length ? (multipleResources ? [hostPorts[resourceIndex]] : [...hostPorts]) : [];
+    if (localPorts.length > 0 && localPorts.length !== remotePorts.length)
+      throw new Error(
+        `Host/container port counts differ for ${kindType}/${resource.NAME}: ${localPorts.length}/${remotePorts.length}`,
+      );
+    return { resource, remotePorts, localPorts };
+  });
+
+  const plan = [];
+  const usedLocalPorts = new Set();
+  for (const { resource, remotePorts, localPorts } of portGroups)
+    for (const [portIndex, remotePort] of remotePorts.entries()) {
+      const explicitLocalPort = localPorts[portIndex];
+      let localPort = explicitLocalPort || remotePort;
+      if (explicitLocalPort && usedLocalPorts.has(localPort))
+        throw new Error(`Duplicate --expose-host-ports value: ${localPort}`);
+      while (!explicitLocalPort && usedLocalPorts.has(localPort)) localPort++;
+      if (localPort > 65535) throw new Error(`No valid host port remains for ${kindType}/${resource.NAME}`);
+      usedLocalPorts.add(localPort);
+      plan.push({ kindType, name: resource.NAME, localPort, remotePort });
+    }
+  return plan;
+};
+/**
+ * @method gatewayApiEnabledFactory
+ * @description Whether a workflow routes through the Gateway API stack.
+ *
+ * On unless explicitly disabled, in every runner: the Gateway API with QUIC/HTTP3
+ * is the platform's routing stack, and the Contour HTTPProxy set is the fallback
+ * a caller opts into with `--disable-gateway-api`. `--gateway-api` stays
+ * meaningful as an explicit request, so a caller that passes it is never
+ * second-guessed. Reading it from one place is what keeps a runner from
+ * defaulting to a different stack than the one that deployed the routes.
+ * @param {object} [options] - Runner/deploy options.
+ * @returns {boolean} True when the Gateway API stack is in effect.
+ * @memberof ServerConfBuilder
+ */
+const gatewayApiEnabledFactory = (options = {}) => options.gatewayApi === true || options.disableGatewayApi !== true;
+
+/**
+ * @method clusterContextFactory
+ * @description The inverse of {@link ServerConfBuilder.clusterTypeFactory}: a
+ * cluster type as the option flags a runner reads.
+ *
+ * A workflow resolves its cluster type once and passes it to spawned commands as
+ * `--${clusterType}`. A runner invoked in-process gets no such string — it sees
+ * the raw options, where every consumer independently defaults to kind: the
+ * image pull (`docker exec kind-worker`), the node resolution behind hostPath
+ * `nodeAffinity`, and the volume cluster context. This carries the choice across
+ * that boundary.
+ * @param {string} clusterType - `kubeadm` | `k3s` | `kind`.
+ * @returns {{kind: boolean, kubeadm: boolean, k3s: boolean}} Mutually exclusive context flags.
+ * @memberof ServerConfBuilder
+ */
+const clusterContextFactory = (clusterType) => ({
+  kind: clusterType === 'kind',
+  kubeadm: clusterType === 'kubeadm',
+  k3s: clusterType === 'k3s',
+});
+
+/**
+ * @method waitForPort
+ * @description Polls a TCP port until it reaches the wanted state.
+ *
+ * Single source of truth for every "is it listening yet" wait: a port-forward
+ * coming up locally, a freshly provisioned node's sshd, and the closed edge that
+ * proves a reboot actually started. The probe is a native connect rather than a
+ * shelled-out one, so it needs neither a shell nor `timeout` on the host and
+ * reports the same result on every platform.
+ * @param {number} port - Port to probe.
+ * @param {string} [host] - Host to probe.
+ * @param {boolean} [open] - Wanted state: true waits for the port to accept, false waits for it to refuse.
+ * @param {number} [timeoutMs] - Maximum wait window.
+ * @param {number} [intervalMs] - Delay between attempts.
+ * @param {number} [connectTimeoutMs] - Per-attempt connect timeout.
+ * @returns {Promise<boolean>} True once the wanted state is observed, false on timeout.
+ * @memberof ServerConfBuilder
+ */
+const waitForPort = async ({
+  port,
+  host = '127.0.0.1',
+  open = true,
+  timeoutMs = 60 * 1000,
+  intervalMs = 2000,
+  connectTimeoutMs = 5000,
+}) => {
+  const probe = () =>
+    new Promise((resolve) => {
+      const socket = new net.Socket();
+      const done = (reachable) => {
+        socket.destroy();
+        resolve(reachable);
+      };
+      socket.setTimeout(connectTimeoutMs);
+      socket.once('connect', () => done(true));
+      socket.once('timeout', () => done(false));
+      socket.once('error', () => done(false));
+      socket.connect(port, host);
+    });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if ((await probe()) === open) return true;
+    await timer(intervalMs);
+  }
+  logger.warn(`Port ${host}:${port} was not ${open ? 'reachable' : 'closed'} within timeout`, { timeoutMs });
+  return false;
+};
+
 /**
  * Creates and writes the /etc/hosts file for a deployment.
  * @method etcHostFactory
  * @param {Array<string>} hosts - List of hosts to be added to the hosts file.
  * @param {object} options - Options for the hosts file creation.
  * @param {boolean} options.append - Whether to append to the existing hosts file.
- * @returns {object} - Object containing the rendered hosts file.
+ * @param {string} [options.blockId] - Replace an idempotent owned block while preserving unrelated entries.
+ * @param {string} [options.path=/etc/hosts] - Hosts file path; injectable for tests.
+ * @returns {{renderHosts: string, changed: boolean}} Rendered content and whether the file changed.
  * @memberof ServerConfBuilder
  */
 const etcHostFactory = (hosts = [], options = { append: false }) => {
@@ -1957,16 +2994,34 @@ const etcHostFactory = (hosts = [], options = { append: false }) => {
   )} localhost localhost.localdomain localhost4 localhost4.localdomain4
 ::1         localhost localhost.localdomain localhost6 localhost6.localdomain6`;
 
-  if (options && options.append && fs.existsSync(`/etc/hosts`)) {
+  const hostsPath = options?.path || '/etc/hosts';
+  if (options?.blockId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(options.blockId)) throw new Error(`Invalid /etc/hosts block id: ${options.blockId}`);
+    const beginMarker = `# underpost hosts ${options.blockId}:begin`;
+    const endMarker = `# underpost hosts ${options.blockId}:end`;
+    const existing = fs.existsSync(hostsPath) ? fs.readFileSync(hostsPath, 'utf8') : '';
+    const begin = existing.indexOf(beginMarker);
+    const end = begin === -1 ? -1 : existing.indexOf(endMarker, begin);
+    let outsideBlock = existing;
+    if (begin !== -1)
+      outsideBlock = `${existing.slice(0, begin)}${end === -1 ? '' : existing.slice(end + endMarker.length)}`;
+    outsideBlock = outsideBlock.trimEnd();
+    const updated = `${outsideBlock}${outsideBlock ? '\n' : ''}${beginMarker}\n${renderHosts}\n${endMarker}\n`;
+    const changed = updated !== existing;
+    if (changed) fs.writeFileSync(hostsPath, updated, 'utf8');
+    return { renderHosts, changed };
+  }
+
+  if (options && options.append && fs.existsSync(hostsPath)) {
     fs.writeFileSync(
-      `/etc/hosts`,
-      fs.readFileSync(`/etc/hosts`, 'utf8') +
+      hostsPath,
+      fs.readFileSync(hostsPath, 'utf8') +
         `
 ${renderHosts}`,
       'utf8',
     );
-  } else fs.writeFileSync(`/etc/hosts`, renderHosts, 'utf8');
-  return { renderHosts };
+  } else fs.writeFileSync(hostsPath, renderHosts, 'utf8');
+  return { renderHosts, changed: true };
 };
 
 /**
@@ -2256,10 +3311,59 @@ git add .`);
   else logger.info('No changes to publish', { repoName });
 };
 
+/**
+ * @function clusterInstancesFactory
+ * @description Binds the instance ids requested by the `cluster` runner to the
+ * deploys that actually declare them.
+ *
+ * An instance belongs to a deploy through that deploy's own
+ * `conf.instances.json` — nothing else relates the two — so the same id under a
+ * different deploy is a different workload, and an id no deploy declares is a
+ * typo rather than a silent no-op. A deploy without the file simply has no
+ * instances.
+ *
+ * Ids are returned as requested, not expanded: `run instance` owns variant
+ * expansion, so a template id (`mmo-server`) is handed over whole and deploys
+ * its whole family. Hosts *are* expanded, because they are needed before any
+ * 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.
+ * @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 byDeployId = Object.fromEntries(
+    deployList.map((deployId) => {
+      const confPath = `./engine-private/conf/${deployId}/conf.instances.json`;
+      if (requested.length === 0 || !fs.existsSync(confPath)) return [deployId, { ids: [], hosts: [] }];
+      const confInstances = loadConfInstances(deployId);
+      const matched = requested
+        .map((id) => ({ id, instances: selectConfInstances(confInstances, id) }))
+        .filter((entry) => entry.instances.length > 0);
+      return [
+        deployId,
+        {
+          ids: matched.map((entry) => entry.id),
+          hosts: [...new Set(matched.flatMap((entry) => entry.instances.map((instance) => instance.host)))],
+        },
+      ];
+    }),
+  );
+  return {
+    byDeployId,
+    unmatched: requested.filter((id) => !deployList.some((deployId) => byDeployId[deployId].ids.includes(id))),
+  };
+};
+
 export {
   Config,
   loadConf,
   loadConfInstances,
+  normalizeInstanceTopology,
+  dispatchBuildInstanceEnv,
+  loadProjectInstanceEnvBuilder,
   loadInstanceTopology,
   readConfInstances,
   selectConfInstances,
@@ -2282,6 +3386,8 @@ export {
   buildKindPorts,
   buildPortProxyRouter,
   splitFileFactory,
+  generateSecurePassword,
+  resolveReplicaCount,
   getNpmRootPath,
   getUnderpostRootPath,
   writeEnv,
@@ -2306,7 +3412,39 @@ export {
   DEFAULT_DEPLOY_ID,
   loadCronDeployEnv,
   cronDeployIdResolve,
+  clusterContextFactory,
+  clusterTypeFactory,
+  exposeTcpPortsFactory,
+  exposePathPartsFactory,
+  exposePartialMatchesFactory,
+  exposePortListFactory,
+  exposePortPlanFactory,
+  deployHostsFactory,
+  clusterInstancesFactory,
   etcHostFactory,
+  gatewayApiEnabledFactory,
+  instanceHttpRouteRulesFactory,
+  instanceInterceptStatusesFactory,
+  instancePortFactory,
+  instanceProjectPathFactory,
+  instanceProxyRoutesFactory,
+  instanceStatusPageDeployIdFactory,
+  instanceStatusPageEntriesFactory,
+  deployTrafficEntriesFactory,
+  trafficProbePathsFactory,
+  hostIngressFactsFactory,
+  curlStatusChainFactory,
+  hostRenderInstancesFactory,
+  instanceTrafficPlanFactory,
+  isTrafficServingFactory,
+  nextTrafficFactory,
+  schedulableNodeFactory,
+  stopPlanFactory,
+  trafficFromRoutingInfoFactory,
+  trafficTableRowsFactory,
+  resolveEnvScoped,
+  sortInstancesByPath,
+  waitForPort,
   resolveDeployList,
   syncPrivateConf,
   syncDeployIdSources,