underpost 3.2.11 → 3.2.14

package/src/server/conf.js

@@ -10,6 +10,7 @@ import dotenv from 'dotenv';
 import {
   capFirst,
   getCapVariableName,
+  getDirname,
   newInstance,
   orderAbc,
   orderArrayFromAttrInt,
@@ -1295,16 +1296,19 @@ const validateTemplatePath = (absolutePath = '') => {
 /**
  * @method awaitDeployMonitor
  * @description Waits for the deploy monitor.
- * @param {boolean} [init=false] - The init flag.
+ * @param {boolean} [isFinal=false] - If true, logs when the final (non-replica) deployment completes.
  * @param {number} [deltaMs=1000] - The delta ms.
- * @returns {Promise<void>} - The await deploy monitor.
+ * @param {boolean} [callback=false] - The callback.
+ * @returns {Promise<boolean>} - `false` if `container-status=error` was detected, `true` on clean completion.
  * @memberof ServerConfBuilder
  */
-const awaitDeployMonitor = async (init = false, deltaMs = 1000) => {
-  if (init) Underpost.env.set('await-deploy', new Date().toISOString());
+const awaitDeployMonitor = async (isFinal = false, deltaMs = 1000, callback = false) => {
+  if (!callback) Underpost.env.set('await-deploy', new Date().toISOString());
+  if (isFinal) logger.info('Final deployment running (no replica)');
   await timer(deltaMs);
-  if (Underpost.env.get('container-status') === 'error') throw new Error('Container status error');
-  if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor();
+  if (Underpost.env.get('container-status') === 'error') return false;
+  if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor(false, deltaMs, true);
+  return true;
 };
 
 /**
@@ -1420,65 +1424,130 @@ const writeEnv = (envPath, envObj) =>
 
 /**
  * @method buildCliDoc
- * @description Builds the CLI documentation.
- * @param {object} program - The program.
- * @param {string} oldVersion - The old version.
- * @param {string} newVersion - The new version.
+ * @description Scrapes `node bin help` (and `node bin help <command>` for every
+ * registered command) and renders a structured Markdown reference: a command
+ * index with anchor links, plus a per-command section with its description,
+ * usage, and Arguments/Options rendered as tables. Writes
+ * `CLI-HELP.md` + the served reference doc, and refreshes the README CLI index.
+ * @param {object} program - The commander program.
+ * @param {string} oldVersion - The old version string to replace.
+ * @param {string} newVersion - The new version string.
  * @memberof ServerConfBuilder
  */
 const buildCliDoc = (program, oldVersion, newVersion) => {
-  let md = shellExec(`node bin help`, { silent: true, stdout: true }).split('Options:');
-  const baseOptions =
-    `## ${md[0].split(`\n`)[2]}
-
-### Usage: ` +
-    '`' +
-    md[0].split(`\n`)[0].split('Usage: ')[1] +
-    '`' +
-    `
-  ` +
-    '```\n Options:' +
-    md[1] +
-    ' \n```';
-  md =
-    baseOptions +
-    `
-
-## Commands:
-    `;
-  program.commands.map((o) => {
-    md +=
-      `
-
-` +
-      '### `' +
-      o._name +
-      '` :' +
-      `
-` +
-      '```\n ' +
-      shellExec(`node bin help ${o._name}`, { silent: true, stdout: true }) +
-      ' \n```' +
-      `
-  `;
-  });
-  md = md.replaceAll(oldVersion, newVersion);
+  const help = (args = '') => shellExec(`node bin help${args ? ` ${args}` : ''}`, { silent: true, stdout: true });
+  // Escape table-breaking pipes and collapse wrapped whitespace for a Markdown cell.
+  const cell = (s) => String(s).replace(/\s+/g, ' ').replaceAll('|', '\\|').trim();
+  const anchor = (name) => `underpost-${name}`.toLowerCase().replace(/[^a-z0-9-]/g, '');
+
+  // Parse a commander help block into { usage, description, sections: { Options, Arguments, Commands } }.
+  const parseHelp = (text) => {
+    const lines = text.split('\n');
+    const usageMatch = lines[0].match(/^Usage:\s*(.*)$/);
+    const usage = usageMatch ? usageMatch[1].trim() : '';
+    const sections = {};
+    const descLines = [];
+    let current = null;
+    let buf = [];
+    const flush = () => {
+      if (current) sections[current] = buf.join('\n');
+      buf = [];
+    };
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      const head = line.match(/^([A-Za-z][\w ]*):\s*$/); // top-level "Options:", "Arguments:", "Commands:"
+      if (head) {
+        flush();
+        current = head[1].trim();
+      } else if (current !== null) {
+        buf.push(line);
+      } else {
+        descLines.push(line);
+      }
+    }
+    flush();
+    return { usage, description: descLines.join('\n').trim(), sections };
+  };
+
+  // Parse a columnar "  <term>   <description>" section (descriptions may wrap onto
+  // indented continuation lines) into [{ term, desc }].
+  const parseEntries = (text = '') => {
+    const entries = [];
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      const leading = line.length - line.trimStart().length;
+      if (leading <= 2) {
+        const rest = line.trim();
+        const gap = rest.search(/\s{2,}/);
+        entries.push(gap === -1 ? { term: rest, desc: '' } : { term: rest.slice(0, gap), desc: rest.slice(gap) });
+      } else if (entries.length) {
+        entries[entries.length - 1].desc += ` ${line.trim()}`;
+      }
+    }
+    return entries;
+  };
+
+  const table = (head, entries) =>
+    !entries.length
+      ? ''
+      : `| ${head[0]} | ${head[1]} |\n| --- | --- |\n` +
+        entries.map(({ term, desc }) => `| \`${cell(term)}\` | ${cell(desc)} |`).join('\n') +
+        '\n';
+
+  const detailSection = (sections, name, head) => {
+    const t = table(head, parseEntries(sections[name]));
+    return t ? `\n#### ${name}\n\n${t}` : '';
+  };
+
+  // ── Top-level index ──
+  const root = parseHelp(help());
+  const commandEntries = parseEntries(root.sections['Commands']).filter((e) => e.term.split(' ')[0] !== 'help');
+
+  const index =
+    `## Underpost CLI\n\n` +
+    (root.description ? `> ${root.description.replace(/\s+/g, ' ')}\n\n` : '') +
+    `**Usage:** \`${root.usage}\`\n\n` +
+    `### Global options\n\n${table(['Option', 'Description'], parseEntries(root.sections['Options']))}\n` +
+    `### Commands\n\n| Command | Description |\n| --- | --- |\n` +
+    commandEntries
+      .map((e) => {
+        const name = e.term.split(' ')[0];
+        return `| [\`${name}\`](#${anchor(name)}) | ${cell(e.desc)} |`;
+      })
+      .join('\n') +
+    '\n';
+
+  // ── Per-command detail ──
+  let details = `\n## Command reference\n`;
+  for (const cmd of program.commands) {
+    const name = cmd._name;
+    if (name === 'help') continue;
+    const cmdHelp = parseHelp(help(name));
+    details +=
+      `\n### \`underpost ${name}\`\n\n` +
+      (cmdHelp.description ? `${cmdHelp.description.replace(/\s+/g, ' ')}\n\n` : '') +
+      `**Usage:** \`${cmdHelp.usage}\`\n` +
+      detailSection(cmdHelp.sections, 'Arguments', ['Argument', 'Description']) +
+      detailSection(cmdHelp.sections, 'Options', ['Option', 'Description']);
+  }
+
+  const md = `${index}${details}`.replaceAll(oldVersion, newVersion);
   fs.writeFileSync(`./src/client/public/nexodev/docs/references/Command Line Interface.md`, md, 'utf8');
   fs.writeFileSync(`./CLI-HELP.md`, md, 'utf8');
 
-  // Update README.md: replace version and CLI index section between comment tags
-  let readme = fs.readFileSync(`./README.md`, 'utf8');
-  readme = readme.replaceAll(oldVersion, newVersion);
+  // Update README.md: bump version and refresh the CLI index between the comment tags.
+  let readme = fs.readFileSync(`./README.md`, 'utf8').replaceAll(oldVersion, newVersion);
   const cliStartTag = '<!-- cli-index-start -->';
   const cliEndTag = '<!-- cli-index-end -->';
   const startIdx = readme.indexOf(cliStartTag);
   const endIdx = readme.indexOf(cliEndTag);
   if (startIdx !== -1 && endIdx !== -1) {
+    const readmeIndex = index.replace(/\(#(underpost-[a-z0-9-]+)\)/g, '(CLI-HELP.md#$1)');
     readme =
       readme.substring(0, startIdx) +
       cliStartTag +
       '\n' +
-      baseOptions +
+      readmeIndex.replaceAll(oldVersion, newVersion) +
       '\n' +
       cliEndTag +
       readme.substring(endIdx + cliEndTag.length);
@@ -1747,6 +1816,219 @@ ${renderHosts}`,
   return { renderHosts };
 };
 
+/**
+ * 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`; 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.readFileSync('./engine-private/deploy/dd.router', 'utf8') : 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`).
+ *
+ * @method syncPrivateConf
+ * @param {string} deployId - A concrete deploy id (e.g. `dd-cyberia`), not the `dd` meta id.
+ * @param {string[]} [extraPaths=[]] - Extra `./engine-private` payload paths to mirror (from the
+ *   deploy's product catalog), kept out of this module so it stays product-agnostic.
+ * @returns {void}
+ * @memberof ServerConfBuilder
+ */
+const syncPrivateConf = (deployId, extraPaths = []) => {
+  const suffix = deployId.split('dd-')[1];
+  const privateRepoName = `engine-${suffix}-private`;
+  const privateGitUri = `${process.env.GITHUB_USERNAME}/${privateRepoName}`;
+  const privateRepoPath = `../${privateRepoName}`;
+
+  if (!fs.existsSync(privateRepoPath)) {
+    shellExec(`cd .. && underpost clone ${privateGitUri}`, { silent: true });
+  } else {
+    shellExec(`cd ${privateRepoPath} && git checkout . && git clean -f -d && underpost pull . ${privateGitUri}`, {
+      silent: true,
+    });
+  }
+
+  const confDest = `${privateRepoPath}/conf/${deployId}`;
+  fs.removeSync(confDest);
+  fs.mkdirSync(confDest, { recursive: true });
+  fs.copySync(`./engine-private/conf/${deployId}`, confDest);
+
+  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}`);
+  }
+
+  for (const extraPath of extraPaths) fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
+
+  shellExec(
+    `cd ${privateRepoPath}` +
+      ` && git add .` +
+      ` && underpost cmt . ci engine-core-conf 'Update ${deployId} conf'` +
+      ` && underpost push . ${privateGitUri}`,
+    { silent: true, silentOnError: true },
+  );
+};
+
+/**
+ * Moves a deploy's public template sources into the engine working tree ahead of
+ * the build copy step. Idempotent and safe to rerun: each move is guarded by
+ * `existsSync`, so already-moved or absent sources are skipped rather than throwing.
+ * The `[src, dest]` pairs come from the deploy's product catalog (passed in), so
+ * this module stays product-agnostic.
+ *
+ * @method syncDeployIdSources
+ * @param {Array<[string, string]>} [sourceMoves=[]] - Public `[src, dest]` move pairs.
+ * @returns {boolean} `true` when any sources were declared, else `false`.
+ * @memberof ServerConfBuilder
+ */
+const syncDeployIdSources = (sourceMoves = []) => {
+  if (!sourceMoves.length) return false;
+  for (const dir of ['src/api', 'src/client/components', 'src/client/public', 'src/client/services'])
+    fs.mkdirSync(dir, { recursive: true });
+  for (const [src, dest] of sourceMoves) if (fs.existsSync(src)) fs.moveSync(src, dest, { overwrite: true });
+  return true;
+};
+
+/**
+ * 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
+ * ({@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`),
+ * 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.
+ * @returns {Promise<void>}
+ * @memberof ServerConfBuilder
+ */
+const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template' } = {}) => {
+  const walk = (await import('ignore-walk')).default;
+  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } = await import('./catalog-underpost.js');
+  const { loadProductCatalogs } = await import('./catalog.js');
+  const githubUsername = process.env.GITHUB_USERNAME;
+
+  logger.info('Build template', { srcPath, toPath });
+
+  const sourceFiles = (
+    await new Promise((resolve) =>
+      walk({ path: srcPath, ignoreFiles: [`.gitignore`], includeEmpty: false, follow: false }, (...args) =>
+        resolve(args[1]),
+      ),
+    )
+  ).filter((p) => !p.startsWith('.git'));
+
+  // Clone the template from 0 if missing; otherwise reset it to a clean pristine checkout.
+  if (!fs.existsSync(toPath)) {
+    shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
+  } else {
+    shellExec(`cd ${toPath} && git reset && git checkout . && git clean -f -d`);
+    shellExec(`node bin pull ${toPath} ${githubUsername}/pwa-microservices-template`);
+    shellExec(`sudo rm -rf ${toPath}/engine-private`);
+    shellExec(`sudo rm -rf ${toPath}/logs`);
+  }
+  shellExec(`cd ${toPath} && git config core.filemode false`);
+
+  for (const copyPath of sourceFiles) {
+    if (copyPath === 'NaN') continue;
+    const absolutePath = `${srcPath}/${copyPath}`;
+    if (!validateTemplatePath(absolutePath)) continue;
+
+    const folder = getDirname(`${toPath}/${copyPath}`);
+    if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+
+    logger.info('build', `${toPath}/${copyPath}`);
+    fs.copyFileSync(absolutePath, `${toPath}/${copyPath}`);
+  }
+
+  fs.copySync(`./.vscode`, `${toPath}/.vscode`);
+  fs.copySync(`./src/client/public/default`, `${toPath}/src/client/public/default`);
+
+  // Preserve the template's own README + package.json identity before merging engine metadata.
+  for (const checkoutPath of ['README.md', 'package.json']) shellExec(`cd ${toPath} && git checkout ${checkoutPath}`);
+
+  // Strip each product catalog's `stripPaths` (aggregated dynamically) plus the engine-only
+  // workflows, deploy manifests, and product catalog modules.
+  const productStripPaths = (await loadProductCatalogs()).flatMap((c) => c.stripPaths);
+  for (const deletePath of productStripPaths) {
+    const target = `${toPath}/${deletePath}`;
+    if (fs.existsSync(target)) fs.removeSync(target);
+  }
+  shellExec(`rm -rf ${toPath}/.github`);
+  shellExec(`rm -rf ${toPath}/manifests/deployment/dd-*`);
+  shellExec(`rm -rf ${toPath}/src/server/catalog-*`);
+
+  fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
+  for (const restorePath of TEMPLATE_RESTORE_PATHS) {
+    const dest = `${toPath}/${restorePath}`;
+    if (fs.statSync(restorePath).isDirectory()) fs.copySync(restorePath, dest, { overwrite: true });
+    else fs.copyFileSync(restorePath, dest);
+  }
+
+  // ── package.json: take engine deps/scripts/version, keep template identity. ──
+  const originPackageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+  const templatePackageJson = JSON.parse(fs.readFileSync(`${toPath}/package.json`, 'utf8'));
+  const templateName = templatePackageJson.name;
+
+  templatePackageJson.dependencies = originPackageJson.dependencies;
+  templatePackageJson.devDependencies = originPackageJson.devDependencies;
+  templatePackageJson.version = originPackageJson.version;
+  templatePackageJson.scripts = originPackageJson.scripts;
+  templatePackageJson.overrides = originPackageJson.overrides;
+  templatePackageJson.name = templateName;
+  templatePackageJson.description = TEMPLATE_DESCRIPTION;
+  templatePackageJson.keywords = TEMPLATE_KEYWORDS;
+  delete templatePackageJson.scripts['build:template'];
+  fs.writeFileSync(`${toPath}/package.json`, JSON.stringify(templatePackageJson, null, 4), 'utf8');
+
+  // ── package-lock.json: mirror engine packages, keep template name/version on the root entry. ──
+  const originPackageLockJson = JSON.parse(fs.readFileSync('./package-lock.json', 'utf8'));
+  const templatePackageLockJson = JSON.parse(fs.readFileSync(`${toPath}/package-lock.json`, 'utf8'));
+  const originBasePackageLock = newInstance(templatePackageLockJson.packages['']);
+  templatePackageLockJson.name = templateName;
+  templatePackageLockJson.version = originPackageLockJson.version;
+  templatePackageLockJson.packages = originPackageLockJson.packages;
+  templatePackageLockJson.packages[''].name = templateName;
+  templatePackageLockJson.packages[''].version = originPackageLockJson.version;
+  templatePackageLockJson.packages[''].hasInstallScript = originBasePackageLock.hasInstallScript;
+  templatePackageLockJson.packages[''].license = originBasePackageLock.license;
+  fs.writeFileSync(`${toPath}/package-lock.json`, JSON.stringify(templatePackageLockJson, null, 4), 'utf8');
+
+  fs.writeFileSync(
+    `${toPath}/README.md`,
+    fs
+      .readFileSync('./README.md', 'utf8')
+      .replace('<!-- template-title -->', '#### Base template for pwa/api-rest projects.'),
+    'utf8',
+  );
+};
+
 export {
   Config,
   loadConf,
@@ -1794,4 +2076,8 @@ export {
   loadCronDeployEnv,
   cronDeployIdResolve,
   etcHostFactory,
+  resolveDeployList,
+  syncPrivateConf,
+  syncDeployIdSources,
+  buildTemplate,
 };

package/src/server/start.js

@@ -211,19 +211,23 @@ class UnderpostStartUp {
           shellExec(`node bin env ${replica} ${env}`);
           const replicaCmd = `npm ${runCmd} ${replica}`;
           shellExec(replicaCmd, { async: true, callback: makeDeployCallback(replicaCmd) });
-          await awaitDeployMonitor(true);
+          const result = await awaitDeployMonitor();
+          if (result !== true) {
+            Underpost.env.set('container-status', 'error');
+            return;
+          }
         }
       }
       shellExec(`node bin env ${deployId} ${env}`);
       const deployCmd = `npm ${runCmd} ${deployId}`;
       shellExec(deployCmd, { async: true, callback: makeDeployCallback(deployCmd) });
-      await awaitDeployMonitor(true);
-      if (Underpost.env.get('container-status') !== 'error') {
+      const result = await awaitDeployMonitor(true);
+      if (result === true) {
         if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
         Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
+      } else {
+        Underpost.env.set('container-status', 'error');
       }
-      Underpost.env.set('container-status', 'error');
-      throw new Error('Deployment process exited unexpectedly');
     },
   };
 }

package/test/deploy-monitor.test.js

@@ -0,0 +1,188 @@
+/**
+ * @module deploy-monitor.test
+ * @description End-to-end test of the deploy readiness/failure contract between
+ * the in-pod runtime (start.js) and the CD-runner monitor
+ * (`Underpost.monitor.monitorReadyRunner`), exercised as two real OS processes
+ * running in parallel and coordinating through the shared underpost env file.
+ *
+ * Contract under test:
+ *
+ *   - start.js (in-pod) only writes `container-status`; it never propagates an
+ *     exit code. On a failed deploy child it sets `container-status=error`; on a
+ *     healthy one it sets `container-status=<deploy>-<env>-running-deployment`.
+ *
+ *   - monitorReadyRunner (CD runner) reads that value per pod (via
+ *     `kubectl exec … underpost config get container-status`) and is the side
+ *     that produces the real process exit: it `throw`s (→ exit 1) on `error`,
+ *     and returns (→ exit 0) once the pod is K8S-Ready AND reports
+ *     `running-deployment`.
+ *
+ * The cluster surface monitorReadyRunner depends on (`sudo`, `kubectl get`,
+ * `kubectl exec`) is supplied by tiny fake binaries on the child's PATH: one
+ * always-Ready pod whose container-status is read straight from the same env
+ * file start.js writes. The env file is redirected under a temp
+ * `npm_config_prefix`, so the test needs no cluster, no root, and never touches
+ * the machine's global install.
+ *
+ * Uses 'chai' for assertions.
+ */
+
+import { expect } from 'chai';
+import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import Underpost from '../src/index.js';
+import { shellExec } from '../src/server/process.js';
+
+const node = process.execPath;
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const DEPLOY_ID = 'dd-test';
+const ENV = 'production';
+const TRAFFIC = 'green';
+const POD_NAME = `${DEPLOY_ID}-${ENV}-${TRAFFIC}-pod`;
+const RUNNING_STATUS = `${DEPLOY_ID}-${ENV}-running-deployment`;
+
+describe('Deploy monitor — start.js ↔ monitorReadyRunner (e2e, parallel processes)', function () {
+  this.timeout(40000);
+
+  let prevPrefix;
+  let tmpPrefix;
+  let fakeBinDir;
+  let envFile;
+  let monitorScriptPath;
+
+  before(() => {
+    prevPrefix = process.env.npm_config_prefix;
+    tmpPrefix = fs.mkdtempSync(path.join(os.tmpdir(), 'underpost-e2e-'));
+    process.env.npm_config_prefix = tmpPrefix;
+
+    // Materialize the underpost env file and resolve its absolute path (the
+    // fake `kubectl exec` reads container-status straight from it).
+    Underpost.env.set('container-status', 'init');
+    const npmRoot = shellExec('npm root -g', { stdout: true, silent: true, disableLog: true }).trim();
+    envFile = path.join(npmRoot, 'underpost', '.env');
+
+    // Fake cluster surface for monitorReadyRunner: a `sudo` that just drops its
+    // flags and execs, and a `kubectl` that reports one always-Ready pod whose
+    // container-status comes from the shared env file.
+    fakeBinDir = path.join(tmpPrefix, 'fakebin');
+    fs.ensureDirSync(fakeBinDir);
+
+    const sudoPath = path.join(fakeBinDir, 'sudo');
+    fs.writeFileSync(
+      sudoPath,
+      `#!/usr/bin/env bash
+while [[ "$1" == -* || "$1" == "--" ]]; do shift; done
+exec "$@"
+`,
+    );
+
+    const kubectlPath = path.join(fakeBinDir, 'kubectl');
+    fs.writeFileSync(
+      kubectlPath,
+      `#!/usr/bin/env bash
+verb="$1"; kind="$2"
+if [[ "$verb" == "get" && "$kind" == "pods" ]]; then
+  printf 'NAME READY STATUS RESTARTS AGE\\n'
+  printf '%s 1/1 Running 0 1m\\n' "$POD_NAME"
+  exit 0
+fi
+if [[ "$verb" == "get" && "$kind" == "pod" ]]; then
+  printf '{"status":{"conditions":[{"type":"Ready","status":"True"}]}}\\n'
+  exit 0
+fi
+if [[ "$verb" == "exec" ]]; then
+  grep -E '^container-status=' "$UNDERPOST_ENV_FILE" 2>/dev/null | tail -n1 | sed -E 's/^container-status=//'
+  exit 0
+fi
+exit 0
+`,
+    );
+    fs.chmodSync(sudoPath, 0o755);
+    fs.chmodSync(kubectlPath, 0o755);
+
+    // Real monitorReadyRunner in its own process: exit 0 when it returns (ready),
+    // exit 1 when it throws (container-status=error). This is the signal `set -e`
+    // turns into a passed/failed GitHub Actions job.
+    monitorScriptPath = path.join(tmpPrefix, 'monitor-ready.mjs');
+    fs.writeFileSync(
+      monitorScriptPath,
+      `import Underpost from ${JSON.stringify(pathToFileURL(path.join(repoRoot, 'src/index.js')).href)};
+try {
+  await Underpost.monitor.monitorReadyRunner(${JSON.stringify(DEPLOY_ID)}, ${JSON.stringify(ENV)}, ${JSON.stringify(
+        TRAFFIC,
+      )}, [], 'default');
+  process.exit(0);
+} catch (_) {
+  process.exit(1);
+}
+`,
+    );
+  });
+
+  after(() => {
+    if (prevPrefix === undefined) delete process.env.npm_config_prefix;
+    else process.env.npm_config_prefix = prevPrefix;
+    fs.removeSync(tmpPrefix);
+  });
+
+  beforeEach(() => {
+    // Deploy in flight: K8S not-yet-running app phase before start.js reports.
+    Underpost.env.set('container-status', `${DEPLOY_ID}-${ENV}-initializing-deployment`);
+  });
+
+  // Spawns the real monitorReadyRunner process with the fake cluster on PATH and
+  // resolves with its exit code.
+  const spawnMonitor = () =>
+    new Promise((resolve) => {
+      const prefix =
+        `PATH="${fakeBinDir}:$PATH" ` +
+        `UNDERPOST_ENV_FILE="${envFile}" ` +
+        `POD_NAME="${POD_NAME}" ` +
+        `npm_config_prefix="${tmpPrefix}"`;
+      shellExec(`${prefix} ${node} ${monitorScriptPath}`, {
+        async: true,
+        silent: true,
+        disableLog: true,
+        callback: (code) => resolve(code),
+      });
+    });
+
+  // Models start.js: runs the deploy as an async child and, mirroring its
+  // `makeDeployCallback`, writes container-status from the child's exit code.
+  // start.js never propagates the failure — it only sets the flag.
+  const runStartJs = (shouldFail) =>
+    new Promise((resolve) => {
+      const deployCmd = `${node} -e "process.exit(${shouldFail ? 1 : 0})"`;
+      shellExec(deployCmd, {
+        async: true,
+        silent: true,
+        disableLog: true,
+        callback: (code) => {
+          if (code !== 0) Underpost.env.set('container-status', 'error');
+          else Underpost.env.set('container-status', RUNNING_STATUS);
+          resolve(code);
+        },
+      });
+    });
+
+  it('error: start.js sets container-status=error and monitorReadyRunner exits 1', async () => {
+    const monitorExit = spawnMonitor();
+    const deployCode = await runStartJs(true);
+
+    expect(deployCode).to.not.equal(0);
+    expect(Underpost.env.get('container-status', undefined, { disableLog: true })).to.equal('error');
+    expect(await monitorExit).to.equal(1);
+  });
+
+  it('success: start.js sets running-deployment and monitorReadyRunner exits 0', async () => {
+    const monitorExit = spawnMonitor();
+    const deployCode = await runStartJs(false);
+
+    expect(deployCode).to.equal(0);
+    expect(Underpost.env.get('container-status', undefined, { disableLog: true })).to.equal(RUNNING_STATUS);
+    expect(await monitorExit).to.equal(0);
+  });
+});