@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/cli/index.js

@@ -2,9 +2,11 @@ import dotenv from 'dotenv';
 import fs from 'fs-extra';
 
 import { Command } from 'commander';
-import { loadConf } from '../server/conf.js';
-import { getNpmRootPath, getUnderpostRootPath } from '../server/environment.js';
+import { deployEnvFactory, getNpmRootPath, getUnderpostRootPath } from '../server/runtime/environment.js';
 import { commitData } from '../client/components/core/CommonJs.js';
+import { registerDomainCommand } from './domains.js';
+import { TEST_TIERS, testSuiteNames } from '../server/build/testing.js';
+import { EXECUTION_PROFILES, profileFromOptionsFactory, setExecutionProfile } from '../server/build/execution.js';
 
 import Underpost from '../index.js';
 
@@ -17,19 +19,38 @@ const program = new Command();
 
 program.name('underpost').description(`underpost ci/cd cli ${Underpost.version}`).version(Underpost.version);
 
+// One gate for every command. The profile decides which classes of side effect this run
+// may cause; `src/server/runtime/process.js` enforces it under all 1400+ call sites, so a
+// command never has to be taught that its environment is unreachable.
+program.option(
+  '--profile <profile>',
+  `Execution profile. One of: ${Object.keys(EXECUTION_PROFILES).join(', ')}.\n` +
+    Object.values(EXECUTION_PROFILES)
+      .map((profile) => `  ${profile.name.padEnd(16)} ${profile.description}`)
+      .join('\n'),
+);
+
+// Resolved before any action runs, from the root flag, the subcommand's own options, or a
+// legacy bypass flag standing in for a profile. Writing it to the environment is what
+// carries it into nested `underpost` invocations.
+program.hook('preAction', (command, actionCommand) => {
+  const profile = profileFromOptionsFactory({ ...command.opts(), ...actionCommand.opts() });
+  if (profile) setExecutionProfile(profile);
+});
+
 program
   .command('new')
   .argument('[app-name]', 'The name of the new project.')
   .option('--deploy-id <deploy-id>', 'Create deploy ID conf env files')
   .option('--sub-conf <sub-conf>', 'Create sub conf env files')
-  .option('--cluster', 'Create deploy ID cluster files and sync to current cluster')
+  .option('--cluster', 'Initialize the base cluster deploy folder engine-private/deploy from ./conf.js')
   .option('--build-repos', 'Create deploy ID repositories')
   .option('--build', 'Build the deployment to pwa-microservices-template (requires --deploy-id)')
   .option('--clean-template', 'Clean the build directory (pwa-microservices-template)')
   .option('--sync-conf', 'Sync configuration to private repositories (requires --deploy-id)')
   .option(
     '--sync-start',
-    "Sync start scripts in deploy ID package.json with root package.json (use 'dd' as --deploy-id to sync all dd.router)",
+    "Sync start scripts in deploy ID package.json with root package.json (use 'dd' as --deploy-id to sync all dd.routes)",
   )
   .option('--purge', 'Remove deploy ID conf and all related repositories (requires --deploy-id)')
   .option('--dev', 'Sets the development cli context')
@@ -53,8 +74,13 @@ program
   .option('--lite-build', 'Skip full build (default is full build)')
   .option('--icons-build', 'Build icons')
   .option('--ssr', 'Rebuild only SSR views defined in conf.ssr.json, leaving client assets untouched')
+  .option(
+    '--env <env>',
+    'Target environment for the build (e.g. "production", "development"). Falls back to --dev, then NODE_ENV.',
+  )
+  .option('--dev', 'Sets the development cli context (shorthand for --env development).')
   .description('Builds client assets, single replicas, and/or syncs environment ports.')
-  .action(Underpost.repo.client);
+  .action(Underpost.client.callback);
 
 program
   .command('start')
@@ -66,7 +92,11 @@ program
   .option('--run', 'Starts application servers and monitors their health.')
   .option('--build', 'Triggers the client-side application build process.')
   .option('--underpost-quickly-install', 'Uses Underpost Quickly Install for dependency installation.')
-  .option('--skip-pull-base', 'Skips cloning repositories, uses current workspace code directly.')
+  .option('--skip-pull-repo-base', 'Skips cloning the engine source repository, uses current workspace code directly.')
+  .option(
+    '--skip-pull-private-repo',
+    'Skips cloning the private configuration repository, uses the engine-private already in the workspace.',
+  )
   .option('--skip-full-build', 'Skips the full client bundle build during deployment.')
   .option(
     '--pull-bundle',
@@ -117,7 +147,7 @@ program
   .option('--hashes <hashes>', 'Comma-separated list of specific file hashes of commits.')
   .option('--extension <extension>', 'specific file extensions of commits.')
   .option('--changelog', 'Print the plain changelog of the last N commits (see --from-n-commit, default 1).')
-  .option('--changelog-build', 'Builds a CHANGELOG.md file based on the commit history')
+  .option('--changelog-build', 'Builds a CHANGELOG.md from the latest five versions')
   .option('--changelog-min-version <version>', 'Sets the minimum version limit for --changelog-build (default: 2.85.0)')
   .option(
     '--changelog-no-hash',
@@ -128,6 +158,12 @@ program
     'Print the sanitized, commit-ready changelog message of the last N commits (see --from-n-commit, default 1). Empty when there are no tagged entries.',
   )
   .option('--from-n-commit <n>', 'Number of latest commits to include in --changelog/--changelog-msg (default: 1).')
+  .option(
+    '--propagate-msg',
+    'Prints the changelog payload carried by the propagation chain, read from the PROPAGATED_MESSAGE ' +
+      'environment variable and stripped of the commit subject wrapper. Falls back to --changelog-msg ' +
+      'over the last N commits (see --from-n-commit) when nothing was propagated.',
+  )
   .option('--unpush', 'With --log, automatically sets range to unpushed commits ahead of remote.')
   .option('-b', 'Shows the current Git branch name.')
   .option('-p [branch]', 'Shows the reflog for the specified branch.')
@@ -158,24 +194,6 @@ program
   .description('Pushes committed changes from a local repository to a remote GitHub repository.')
   .action(Underpost.repo.push);
 
-program
-  .command('env')
-  .argument(
-    '[deploy-id]',
-    `The deployment configuration ID. Use 'clean' to restore default environment settings. Use 'root' to load underpost root env. Use 'current' to get plain current deploy Id.`,
-  )
-  .argument('[env]', 'Optional: The environment to set (e.g., "production", "development"). Defaults to "production".')
-  .argument('[subConf]', 'Optional: The sub configuration to set.')
-  .description('Sets environment variables and configurations related to a specific deployment ID.')
-  .action((deployId, env, subConf) => {
-    if (deployId === 'root') {
-      const underpostRootDeployId = Underpost.env.get('DEPLOY_ID');
-      if (underpostRootDeployId) deployId = underpostRootDeployId;
-    }
-    if (env) process.env.NODE_ENV = env;
-    loadConf(deployId, subConf);
-  });
-
 program
   .command('static')
   .option('--page <ssr-component-path>', 'Build custom static pages.')
@@ -223,19 +241,6 @@ program
   .description(`Manages static build of page, bundles, and documentation with comprehensive customization options.`)
   .action(Underpost.static.callback);
 
-program
-  .command('config')
-  .argument('operator', `The configuration operation to perform. Options: ${Object.keys(Underpost.env).join(', ')}.`)
-  .argument('[key]', 'Optional: The specific configuration key to manage.')
-  .argument('[value]', 'Optional: The value to set for the configuration key.')
-  .option('--plain', 'Prints the configuration value in plain text.')
-  .option('--filter <keyword>', 'Filters the list by matching key or value (only for list operation).')
-  .option('--deploy-id <deploy-id>', 'Sets the deployment configuration ID for the operation context.')
-  .option('--build', 'Sets the build context for the operation.')
-  .option('--copy', 'Copies the configuration value to the clipboard (only for get operation).')
-  .description(`Manages Underpost configurations using various operators.`)
-  .action((...args) => Underpost.env[args[0]](args[1], args[2], args[3]));
-
 program
   .command('root')
   .description('Displays the root path of the npm installation.')
@@ -260,6 +265,11 @@ program
   .option('--unblock-all-egress', 'Unblocks all outbound traffic and restores default ACCEPT policy.')
   .option('--block-all-ingress', 'Blocks all new inbound traffic to this host (keeps established/related connections).')
   .option('--unblock-all-ingress', 'Unblocks all inbound traffic and restores default ACCEPT policy.')
+  .option(
+    '--block-ingress-port <ports>',
+    'Blocks new inbound traffic on comma-separated TCP ports, leaving the management path reachable.',
+  )
+  .option('--unblock-ingress-port <ports>', 'Withdraws the port rules --block-ingress-port installed.')
   .option('--mac', 'Prints the MAC address of the main network interface.')
   .description('Displays the current public machine IP addresses.')
   .action(Underpost.dns.ipDispatcher);
@@ -279,6 +289,12 @@ program
   .option('--service-host <host>', 'Set custom host/IP for exposed MongoDB and Valkey clients.')
   .option('--postgresql', 'Initializes the cluster with a PostgreSQL statefulset.')
   .option('--mongodb4', 'Initializes the cluster with a MongoDB 4.4 service.')
+  .option(
+    '--mongo-express',
+    'Deploys the mongo-express web client for inspecting the MongoDB statefulset databases and collections. ' +
+      'Reuses the mongodb-secret credentials, and drops them when the deployed mongod runs without --auth. ' +
+      'Combine with --node-port to expose it on the node network.',
+  )
   .option('--valkey', 'Initializes the cluster with a Valkey service.')
   .option('--ipfs', 'Initializes the cluster with an ipfs-cluster statefulset.')
   .option('--contour', 'Initializes the cluster with Project Contour base HTTPProxy and Envoy.')
@@ -297,8 +313,9 @@ program
     'Exposes enabled ready services (e.g. MongoDB 4.4, Valkey) to the host/public network via their NodePort Service manifest.',
   )
   .option(
-    '--node-selector <k8s-node-name>',
-    'Pins the just-deployed StatefulSet (MongoDB 4.4 / Valkey) to the given Kubernetes node once it is ready (via a kubernetes.io/hostname nodeSelector).',
+    '--node-name <k8s-node-name>',
+    'Pins the just-deployed workload (MongoDB 4.4 / Valkey StatefulSets, the observability Deployments) ' +
+      'to the given Kubernetes node once it is ready, via a kubernetes.io/hostname nodeSelector.',
   )
   .option('--cert-manager', "Initializes the cluster with a Let's Encrypt production ClusterIssuer.")
   .option('--dedicated-gpu', 'Initializes the cluster with dedicated GPU base resources and environment settings.')
@@ -315,10 +332,15 @@ program
     '--control-plane-endpoint <endpoint>',
     'Sets custom control plane endpoint for kubeadm cluster initialization (defaults to "localhost:6443").',
   )
-  .option('--grafana', 'Initializes the cluster with a Grafana deployment.')
+  .option(
+    '--grafana',
+    'Initializes the cluster with the observability stack (Prometheus, Alertmanager, Blackbox Exporter, Grafana). ' +
+      'Equivalent to --prom; both converge the one stack.',
+  )
   .option(
     '--prom [hosts]',
-    'Initializes the cluster with a Prometheus Operator deployment and monitor scrap for specified hosts.',
+    'Initializes the cluster with the observability stack. Scrape targets are derived from each deploy conf.server.json; ' +
+      'the optional comma-separated hosts are scraped at /metrics in addition to them.',
   )
   .option('--dev', 'Initializes a development-specific cluster configuration.')
   .option('--list-pods', 'Displays detailed information about all pods.')
@@ -427,69 +449,41 @@ program
   .description('Manages application deployments, defaulting to deploying development pods.')
   .action(Underpost.deploy.callback);
 
-program
-  .command('secret')
-  .argument(
-    '[platform]',
-    `The secret management platform. Options: ${Object.keys(Underpost.secret).join(', ')}. Defaults to "sops".`,
-    'sops',
-  )
-  .option('--init', 'Initializes the secrets platform environment.')
-  .option('--create-from-file <path-env-file>', 'Creates secrets from a specified environment file.')
-  .option('--create-from-env', 'Creates secrets from container environment variables (envFrom: secretRef).')
-  .option('--global-clean', 'Removes all filesystem traces of secrets (engine-private, .env, conf cache).')
-  .option('--list', 'Lists all available secrets for the platform.')
-  .option(
-    '--encrypt <plaintext-path>',
-    'Encrypts a plaintext Secret manifest into the Git-tracked SOPS store and shreds the source (sops platform).',
-  )
-  .option(
-    '--apply',
-    'Decrypts stored SOPS manifests and streams them into kubectl apply, without writing plaintext to disk (sops platform).',
-  )
-  .option('--namespace <namespace>', 'Kubernetes namespace for secret operations (defaults to "default").')
-  .option(
-    '--install-tools',
-    'Installs the sops and age host binaries only, without running a full cluster host initialization.',
-  )
-  .option(
-    '--rotate',
-    'Re-keys every stored SOPS manifest onto --recipient. Secret values are unchanged, so no workload restart is needed.',
-  )
-  .option('--recipient <age-public-key>', 'Incoming Age public recipient for --rotate.')
-  .option(
-    '--prune-recipients',
-    'With --rotate, makes --recipient the only recipient, revoking every previous key (use after a key compromise). ' +
-      'Requires --force, and revokes CI/CD keys too unless they are named in --keep-recipients.',
-  )
-  .option(
-    '--keep-recipients <age-public-keys>',
-    'Comma-separated recipients to retain while --prune-recipients revokes the rest (e.g. the CI/CD key).',
-  )
-  .option(
-    '--purge <secret-name>',
-    'Emergency removal: deletes the live Kubernetes Secret and takes its encrypted manifest out of the store.',
-  )
-  .option(
-    '--force',
-    'Confirms the irreversible variant: deletes the manifest instead of archiving it (--purge), ' +
-      'revokes recipients (--rotate --prune-recipients), or replaces an existing manifest (--encrypt).',
-  )
-  .option('--dry-run', 'Reports what --apply, --rotate, or --purge would do without changing anything.')
-  .description(`Manages secrets for various platforms.`)
-  .action((platform, options) => {
-    // Host tooling install is platform-independent, so it resolves before any platform lookup.
-    if (options.installTools) return Underpost.secret.sops.installTooling();
-    if (options.globalClean) return Underpost.secret.globalSecretClean();
-    if (options.rotate) return Underpost.secret[platform].rotate(options.recipient, options);
-    if (options.purge) return Underpost.secret[platform].purge(options.purge, options);
-    if (options.encrypt) return Underpost.secret[platform].encrypt(options.encrypt, options.namespace, options);
-    if (options.apply) return Underpost.secret[platform].apply(options.namespace, options);
-    if (options.createFromFile) return Underpost.secret[platform].createFromEnvFile(options.createFromFile);
-    if (options.createFromEnv) return Underpost.secret[platform].createFromContainerEnv();
-    if (options.list) return Underpost.secret[platform].list();
-    if (options.init) return Underpost.secret[platform].init();
-  });
+// The four domains are registered from one factory, so their action list and their option list
+// exist exactly once. Adding a verb or a flag here adds it to all four; there is no place to add
+// one to a single domain.
+for (const domain of [
+  {
+    name: 'secret',
+    description: 'Workload secret store: SOPS/Age encrypted credentials projected as Kubernetes Secrets.',
+    api: () => Underpost.secret,
+  },
+  {
+    // The only store-owning domain: `host get|set|delete|list` reads and writes the host
+    // configuration store this domain already owns end to end, so there is no second command
+    // addressing the same file. Container status is not here — it is `underpost state`.
+    name: 'host',
+    description: 'Host configuration: the node-level operational environment shared by the cluster.',
+    api: () => Underpost.host,
+    store: true,
+  },
+  {
+    name: 'app',
+    description: "Application environment: one deployment's runtime configuration.",
+    api: () => Underpost.app,
+  },
+  {
+    // The runtime monitoring / telemetry layer. Unlike the other three it has no durable
+    // source — an observation is only true of a running container — so its `load` collects from
+    // the live workload and its `publish` exports off-cluster. Its store is the container state
+    // store, never the host domain's: different owner, different lifetime.
+    name: 'state',
+    description: 'Runtime state: live container execution state, health and metrics, exported off-cluster.',
+    api: () => Underpost.state,
+    store: true,
+  },
+])
+  registerDomainCommand(program, domain);
 
 program
   .command('image')
@@ -548,7 +542,6 @@ program
   )
   .option('--all-pods', 'Target all matching pods instead of just the first one.')
   .option('--primary-pod', 'Automatically detect and use MongoDB primary pod (MongoDB only).')
-  .option('--primary-pod-ensure <pod-name>', 'Ensure setup of MongoDB replica set primary pod before operations.')
   .option('--stats', 'Display database statistics (collection/table names with document/row counts).')
   .option('--collections <collections>', 'Comma-separated list of database collections to operate on.')
   .option('--out-path <out-path>', 'Specifies a custom output path for backups.')
@@ -614,7 +607,11 @@ program
   )
   .option('--namespace <namespace>', 'Kubernetes namespace for the CronJob resources (default: "default").')
   .option('--image <image>', 'Custom container image for the CronJob pods.')
-  .option('--node-name <node-name>', 'Pins the CronJob pods to this node via a kubernetes.io/hostname nodeSelector.')
+  .option(
+    '--node-name <node-name>',
+    'Pins the CronJob pods to this node via a kubernetes.io/hostname nodeSelector. ' +
+      'With --apply, defaults to this machine when the cluster knows it as a node, because the pods mount its checkout.',
+  )
   .option('--git', 'Pass --git flag to cron job execution.')
   .option('--cmd <cmd>', 'Optional pre-script commands to run before cron execution.')
   .option('--dev', 'Use local ./ base path instead of global underpost installation.')
@@ -631,33 +628,31 @@ program
 
 program
   .command('fs')
-  .argument('[path]', 'The absolute or relative directory path for file operations.')
-  .option('--rm', 'Removes the specified file.')
-  .option('--git', 'Displays current Git changes related to file storage.')
-  .option('--recursive', 'Uploads files recursively from the specified path.')
-  .option('--deploy-id <deploy-id>', 'Specifies the deployment configuration ID for file operations.')
-  .option('--pull', 'Downloads the specified file.')
+  .argument('[path]', 'Selects one file or all files below a directory. Required unless --tracked is set.')
+  .option('--rm', 'Deletes selected remote assets and their manifest entries.')
+  .option('--git', 'Restricts filesystem selection to Git-tracked files. Does not change Git state.')
+  .option('--recursive', 'Compatibility option. Directories always select files recursively.')
+  .option('--tracked', 'Selects only manifest entries. An optional path limits their scope.')
+  .requiredOption('--deploy-id <deploy-id>', 'Selects the deployment configuration.')
+  .option('--pull', 'Downloads selected manifest assets. Use --tracked to restore missing local files.')
   .option('--omit-unzip', 'With --pull, keeps the downloaded .zip file and skips extraction.')
-  .option('--force', 'Forces the action, overriding any warnings or conflicts.')
-  .option('--storage-file-path <storage-file-path>', 'Specifies a custom file storage path.')
-  .description('Manages file storage, defaulting to file upload operations.')
+  .option('--force', 'Overwrites remote uploads or local downloads. Does not change selection.')
+  .option('--storage-id <sub-id>', 'Selects storage.<sub-id>.json. The default is storage.json.')
+  .option('--key <path>', 'Selects one exact manifest key within the path scope and filters.')
+  .option('--from-key <path>', 'Starts an inclusive range in manifest key order.')
+  .option('--to-key <path>', 'Ends an inclusive range. The default start is the first manifest key.')
+  .option('--key-regex <pattern>', 'Filters manifest keys by a JavaScript regular expression.')
+  .description('Uploads, pulls, or deletes Cloudinary assets and synchronizes the selected storage manifest.')
   .action(Underpost.fs.callback);
 
-program
-  .command('test')
-  .argument('[deploy-list]', 'A comma-separated list of deployment IDs (e.g., "default-a,default-b").')
-  .description('Manages and runs tests, defaulting to the current Underpost default test suite.')
-  .option('--itc', 'Executes tests within the container execution context.')
-  .option('--sh', 'Copies the container entrypoint shell command to the clipboard.')
-  .option('--logs', 'Displays container logs for test debugging.')
-  .option('--pod-name <pod-name>', 'Optional: Specifies the pod name for test execution.')
-  .option('--pod-status <pod-status>', 'Optional: Filters tests by pod status.')
-  .option('--kind-type <kind-type>', 'Optional: Specifies the Kind cluster type for tests.')
-  .action(Underpost.test.callback);
-
 program
   .command('monitor')
-  .argument('<deploy-id>', 'The deployment configuration ID to monitor.')
+  .argument(
+    '[deploy-id]',
+    'The deployment configuration ID to monitor. With the observability flags it selects which deploys are scraped; ' +
+      '"dd" covers every deploy in dd.routes.',
+    'dd',
+  )
   .argument(
     '[env]',
     'Optional: The environment to monitor (e.g., "development", "production"). Defaults to "development".',
@@ -677,12 +672,104 @@ program
   .option('--versions <deployment-versions>', 'Specifies the deployment versions to monitor. eg. "blue,green", "green"')
   .option('--ready-deployment', 'Run in ready deployment monitor mode.')
   .option('--promote', 'Promotes the deployment after monitoring.')
-  .description('Manages health server monitoring for specified deployments.')
+  .option(
+    '--observability',
+    'Deploys or converges the cluster observability stack (Prometheus, Alertmanager, Blackbox Exporter, Grafana), ' +
+      'ensuring the Gateway API metrics source and local-path storage provisioner are ready.',
+  )
+  .option(
+    '--sync-prom',
+    'Regenerates the scrape configuration, alert rules and Alertmanager route from the live deploy configuration ' +
+      'and event registry, applies Grafana admin credentials, then reloads or rolls only the affected component.',
+  )
+  .option('--events <event-ids>', 'Comma-separated event ids to provision; empty provisions every registered event.')
+  .option(
+    '--webhook-url <url>',
+    'URL Alertmanager delivers events to (defaults to the node address of `event --serve`).',
+  )
+  .option('--extra-targets <targets>', 'Comma-separated additional "host:port" scrape targets.')
+  .option(
+    '--metrics-server',
+    'Installs the Kubernetes metrics-server (kubectl top / HPA resource API). Skipped on K3s, which bundles its own, unless --force.',
+  )
+  .option(
+    '--cockpit',
+    'Installs and enables the Cockpit KVM dashboard on this host (cockpit, cockpit-machines, libvirt) and opens its firewall service.',
+  )
+  .option('--cockpit-stop', 'Stops and disables the Cockpit KVM dashboard and closes its firewall service.')
+  .option(
+    '--grafana-host <host>',
+    'Publishes Grafana at https://<host>/grafana through the edge Gateway that already serves that hostname.',
+  )
+  .option('--node-port', "Publishes Grafana on the node's LAN address (port 32300).")
+  .option('--expose-grafana', 'Republishes Grafana with --grafana-host / --node-port without redeploying the stack.')
+  .option(
+    '--webhook-token',
+    'Prints the shared event webhook token, to persist as UNDERPOST_EVENT_TOKEN in the cron deploy env.',
+  )
+  .option(
+    '--node-name <k8s-node-name>',
+    'Pins every monitoring workload to this node; moving Grafana deletes and recreates its node-local data.',
+  )
+  .option('--kubeadm', 'Treats the cluster as kubeadm when resolving node and host addresses.')
+  .option('--kind', 'Treats the cluster as Kind (Docker nodes) when resolving node and host addresses.')
+  .option('--k3s', 'Treats the cluster as K3s when resolving node and host addresses.')
+  .option('--force', 'Confirms an install that would replace a bundled component (e.g. --metrics-server on K3s).')
+  .option('--dev', 'Sets the development cli context (scrapes over HTTP, defaults the cluster type to Kind).')
+  .description('Manages health server monitoring, the cluster observability stack, and host dashboards.')
   .action(Underpost.monitor.callback);
 
+program
+  .command('event')
+  .argument('[event-id]', `The operational event to dispatch. Options: ${Object.keys(Underpost.event.EVENTS)}.`)
+  .option(
+    '--deploy',
+    'Merges the event into the set already deployed in the cluster and republishes the monitoring configuration.',
+  )
+  .option('--undeploy', 'Removes the event from the deployed set and republishes without it.')
+  .option(
+    '--suspend-events <state-file>',
+    'Saves the exact deployed event set and temporarily republishes observability without event probes or alerts.',
+  )
+  .option(
+    '--resume-events <state-file>',
+    'Restores and resynchronizes the exact event set saved by --suspend-events, then removes the state file.',
+  )
+  .option('--serve', 'Runs the Alertmanager webhook receiver in the foreground (use --service to supervise it).')
+  .option(
+    '--service',
+    'Installs the receiver on a WireGuard control node as the underpost-event systemd unit. ' +
+      'It remains available while the tunnel is down.',
+  )
+  .option('--service-stop', 'Stops, disables and removes the underpost-event systemd unit.')
+  .option('--service-status', 'Reports whether the underpost-event unit is active and enabled.')
+  .option('--list', 'Lists the registered events with their resolved probe targets.')
+  .option('--port <port>', 'Listening port for --serve and the generated unit (default: 39099).')
+  .option('--cooldown-ms <ms>', 'Minimum interval between two dispatches of one event in --serve (default: 10000).')
+  .option(
+    '--spoke <spoke-id>',
+    'Spoke to remediate when dispatching wireguard-spoke-down by hand; a webhook takes it from the alert labels.',
+  )
+  .option(
+    '--nodes <node-names>',
+    'Comma-separated node documents to act on — hubs for wireguard-server-down, peers for wireguard-spoke-down. ' +
+      'Empty covers every registered hub, or every peer of this node hub.',
+  )
+  .option('--namespace <namespace>', 'Kubernetes namespace holding the observability stack. Defaults to "default".')
+  .option('--webhook-url <url>', 'URL Alertmanager delivers to, written into the generated route with --deploy.')
+  .option('--dev', 'Sets the development cli context.')
+  .option('--dry-run', 'Reports the remediation the event would run without executing it.')
+  .option('--no-notify', 'Skips the operational alert declared in engine-private/deploy/conf.event.json.')
+  .option(
+    '--e2e-test',
+    'Rehearses the event against the live edge: breaks the real subject, waits for the probe to fail, ' +
+      'runs the remediation, and verifies the notification was actually sent.',
+  )
+  .description('Dispatches operational events and provisions the monitoring rules that trigger them.')
+  .action(Underpost.event.callback);
+
 program
   .command('ssh')
-  .option('--deploy-id <deploy-id>', 'Sets deploy id context for ssh operations.')
   .option('--generate', 'Generates new ssh credential and stores it in current private keys file storage.')
   .option('--user <user>', 'Sets custom ssh user')
   .option('--password <password>', 'Sets custom ssh password')
@@ -701,9 +788,10 @@ program
   .option('--key-test', 'Tests the SSH key using ssh-keygen.')
   .option('--stop', 'Stops the SSH service.')
   .option('--status', 'Checks the status of the SSH service.')
-  .option('--connect-uri', 'Displays the connection URI.')
-  .option('--copy', 'Copies the connection URI to clipboard.')
-  .description('Manages SSH credentials and sessions for remote access to cluster nodes or services.')
+  .description(
+    'Manages cluster scoped SSH credentials and sessions for remote access to cluster nodes or services. ' +
+      'Users are registered in engine-private/deploy/conf.users.json and keys are stored in engine-private/deploy/users/<user>.',
+  )
   .action(Underpost.ssh.callback);
 
 // `underpost wireguard` and `underpost haproxy` are two entrypoints onto one
@@ -716,28 +804,36 @@ const edgeCommandFactory = (name, description) =>
     .option(
       '--deploy-id <deploy-id>',
       'Deploy IDs whose conf.server.json/conf.instances.json define the routes. ' +
-        'Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.router, ' +
+        'Accepts one id or a comma-separated list; defaults to "dd", every deploy in dd.routes, ' +
         'because the edge holds one pair of map files for the whole cluster.',
     )
     .option('--interface <name>', 'WireGuard interface name (default: "wg0").')
     .option('--wireguard-install', 'Installs the wireguard-tools, haproxy and iptables host packages.')
     .option('--wireguard-setup', 'Generates keys, builds the interface config, and applies local network rules.')
-    .option('--server', 'Configures this node as the hub endpoint accepting inbound tunnel traffic.')
-    .option('--client', 'Configures this node as a spoke endpoint maintaining an outbound tunnel.')
+    .option('--node-config', 'Writes a node identity under deploy/nodes, named after the machine it describes.')
+    .option(
+      '--node-name <node-name>',
+      'Node record to write; defaults to this hostname, which is what runtime commands resolve their identity by.',
+    )
+    .option('--node-role <role>', 'Machine role: control, worker, or hub.')
+    .option('--hub-host <ipv4>', 'Static public IPv4 key of the hub topology this node belongs to.')
     .option('--port <port>', 'WireGuard UDP listening port (default: 51820).')
     .option(
       '--cidr <cidr>',
-      'Hub interface address with prefix when used with --server (e.g. "10.0.0.1/24"); ' +
-        'the overlay subnet a spoke routes back through the hub when used with --client (default: "10.0.0.0/24").',
+      'Hub interface address on a hub; overlay subnet routed through the hub on control and worker nodes.',
     )
-    .option('--peer-ip <ip>', 'Tunnel address of the target spoke. Required with --client and --peer-add.')
-    .option('--endpoint <host:port>', 'Hub host and port a spoke dials. Required with --client.')
-    .option('--public-key <key>', 'Hub public key with --client; spoke public key with --peer-add.')
+    .option('--peer-ip <ip>', 'Tunnel address used by --peer-add or to update the selected node during setup.')
+    .option('--peer-id <peer-id>', 'Topology peer represented by a control or worker node identity.')
+    .option('--public-key <key>', 'Public key used by off-host topology authoring or --peer-add.')
     .option('--peer-add <peer-id>', 'Registers a spoke and applies it to the running hub without a restart.')
-    .option('--peer-remove <peer-id>', 'Removes a spoke from the registry and from the running hub.')
+    .option('--peer-remove <peer-id>', 'Removes a peer from the selected topology and running hub.')
     .option('--allowed-ips <cidrs>', 'Comma-separated CIDRs routed to the spoke (e.g. "10.0.0.2/32,192.168.10.0/24").')
     .option('--hosts <hosts>', 'Comma-separated hostnames bound to the spoke, overriding instance resolution.')
     .option('--instances <instances>', 'Comma-separated conf.instances.json ids bound to the spoke.')
+    .option(
+      '--management-host <host>',
+      'Stable LAN or management address used to repair this peer when its tunnel address is unavailable.',
+    )
     .option('--default', 'Marks the spoke as the fallback for hostnames that match no other binding.')
     .option('--haproxy-setup', 'Installs HAProxy, publishes the current routes, and enables the daemon.')
     .option('--haproxy-sync', 'Recompiles the SNI/Host maps from deploy config and hot-reloads HAProxy.')
@@ -750,7 +846,7 @@ const edgeCommandFactory = (name, description) =>
       '--build-conf',
       'Writes only engine-private/deploy/conf.wireguard.json and touches no host state. ' +
         'Combine with --wireguard-setup / --peer-add / --peer-remove to author the topology off-box; ' +
-        'alone it normalizes and validates the existing registry.',
+        'alone it normalizes and validates the existing topology.',
     )
     .option(
       '--forward-proxy-server',
@@ -761,18 +857,58 @@ const edgeCommandFactory = (name, description) =>
     )
     .option(
       '--forward-proxy-server-host <host>',
-      'Address the forward proxy binds, overriding the hub tunnel address from the registry.',
+      'Address the forward proxy binds, overriding the selected hub tunnel address.',
     )
     .option('--forward-proxy-server-port <port>', 'Port the forward proxy binds (default: 1080).')
     .option(
       '--ssh-forward-port <port>',
       'Publishes the default spoke SSH port on this public TCP port of the hub, so CI with no fixed ' +
-        'address can reach the cluster node (e.g. 2222). "0" closes it. Stored in the registry.',
+        'address can reach the cluster node (e.g. 2222). "0" closes it. Stored in hub topology.',
+    )
+    .option(
+      '--sync',
+      'Brings every registered node engine checkout up to date over its SSH identity: clean, pull, fix and install.',
+    )
+    .option(
+      '--nodes <node-names>',
+      'Comma-separated node documents --sync, --cmd, --node-exporter and --connect-uri act on. ' +
+        'Empty covers every hub and every peer of this node hub.',
+    )
+    .option(
+      '--connect-uri',
+      'Prints the SSH command that reaches each node named by --nodes, joining the node document under ' +
+        'engine-private/deploy/nodes to the management address it is registered under in ' +
+        'engine-private/deploy/conf.users.json. Empty --nodes lists the whole fleet.',
+    )
+    .option('--copy', 'Copies the --connect-uri output to the clipboard instead of printing it.')
+    .option(
+      '--cmd <command-list>',
+      'Comma-separated custom commands to run on the selected nodes over their SSH identity. ' +
+        'Given with --sync, only these run in place of the sync steps.',
+    )
+    .option(
+      '--node-exporter',
+      'Provisions the host metrics collector as a systemd service on the selected hub nodes, bound to their ' +
+        'tunnel address, so machines outside the cluster report hardware metrics like every cluster node.',
+    )
+    .option(
+      '--repo-engine <repo>',
+      'Engine repository --sync pulls from, as owner/repo or a clone URL. Defaults to the configured account engine.',
+    )
+    .option(
+      '--repo-engine-private <repo>',
+      'Private engine repository --sync pulls from, as owner/repo or a clone URL. ' +
+        'Defaults to the configured private repo derived from --repo-engine.',
     )
     .option('--wireguard-start', 'Enables and starts wg-quick@<interface> and the QUIC forward.')
+    .option('--wireguard-restart', 'Restarts wg-quick@<interface> and restores the hub QUIC forward.')
     .option('--wireguard-stop', 'Tears down the interface and removes its transient packet rules.')
-    .option('--wireguard-reset', 'Removes generated configs and packet rules, keeping the key pair and registry.')
-    .option('--wireguard-reinstall', 'Full purge, package reinstall and re-key; every spoke must re-register.')
+    .option('--check', 'Waits for an active interface and a fresh handshake with its required peer.')
+    .option('--check-timeout <seconds>', 'Maximum wait for --check (default: 30).')
+    .option('--expected-role <role>', 'Refuses restart/check unless this host has the expected node role.')
+    .option('--expected-id <peer-id>', 'Refuses restart/check unless this node represents the expected peer id.')
+    .option('--wireguard-reset', 'Removes generated host state, keeping keys, topology and node identity.')
+    .option('--wireguard-reinstall', 'Full purge, package reinstall and re-key; updates the selected topology key.')
     .option('--dry-run', 'Prints the files and commands the run would apply, without touching the host.')
     .description(description)
     .action(Underpost.wireguard.callback);
@@ -842,6 +978,12 @@ program
   .option('--volume-mount-path <volume-mount-path>', 'Optional: Specifies the volume mount path for test execution.')
   .option('--volume-type <volume-type>', 'Optional: Specifies the volume type for test execution.')
   .option('--image-name <image-name>', 'Optional: Specifies the image name for test execution.')
+  .option('--image <image>', 'Container image the deployment pulls and runs (sync).')
+  .option('--runtime-image <name>', 'src/runtime/<name> image family the cluster runner brings up (default "express").')
+  .option(
+    '--versions <deployment-versions>',
+    'Comma-separated blue/green deployment versions (sync); unset resolves the next colour.',
+  )
   .option('--container-name <container-name>', 'Optional: Specifies the container name for test execution.')
   .option('--namespace <namespace>', 'Optional: Specifies the namespace for test execution.')
   .option('--tty', 'Enables TTY for the container in deploy-job.')
@@ -895,6 +1037,7 @@ program
   .option('--deploy-id <deploy-id>', 'Sets deploy id context for the runner execution.')
   .option('--user <user>', 'Sets user context for the runner execution.')
   .option('--hosts <hosts>', 'Comma-separated list of hosts for the runner execution.')
+  .option('--split <mb>', 'Zip part size in MB for push-bundle, or "none" to upload a single zip. Defaults to 8.')
   .option('--instance-id <instance-id>', 'Sets instance id context for the runner execution.')
   .option('--pid <process-id>', 'Sets process id context for the runner execution.')
   .option(
@@ -919,6 +1062,11 @@ program
     'Omits the QUIC/HTTP3 listener config and the Alt-Svc advertisement from Gateway API manifests.',
   )
   .option('--quic-port <port>', 'UDP port advertised for QUIC/HTTP3 in generated Gateway API manifests (default 443).')
+  .option(
+    '--repo-engine-private <repo>',
+    'Private configuration repository the pull runner checks out, as owner/repo or a clone URL. ' +
+      'Defaults to the private repo derived from the engine source.',
+  )
   .option('--disable-private-conf-update', 'Disables updates to private configuration during execution.')
   .option('--logs', 'Streams logs during the runner execution.')
   .option('--monitor-status <status>', 'Sets the status to monitor for pod/resource (default: "Running").')
@@ -967,6 +1115,33 @@ program
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
+program
+  .command('test')
+  .argument(
+    '[suite]',
+    `A comma-separated list of suites or tiers to run. Suites: ${testSuiteNames().join(', ')}. ` +
+      `Tiers: ${TEST_TIERS.map(({ name }) => name).join(', ')}. Defaults to every tier, in tier order.`,
+    '',
+  )
+  .option('--itc', 'Runs in this execution context instead of dispatching into deployment pods.')
+  .option('--deploy-list <deploy-list>', 'A comma-separated list of deployment IDs to run the suite inside.')
+  .option('--grep <pattern>', 'Runs only tests whose name matches the pattern.')
+  .option('--watch', 'Keeps the runner open and re-runs affected suites on change.')
+  .option('--no-coverage', 'Skips coverage instrumentation and reporters.')
+  .option('--allure', 'Writes Allure results for the cluster dashboard alongside the run.')
+  .option('--dashboard', 'Applies the Allure dashboard to the cluster and exits.')
+  .option('--job', 'Runs the selected suite on the cluster as a Kubernetes Job (requires --image).')
+  .option('--image <image>', 'Image carrying the engine and its dependencies, for --job.')
+  .option('--node-name <node-name>', 'Pins the --job pod to this node.')
+  .option('--host <host>', 'Hostname to route the --dashboard sub-path on.')
+  .option('--namespace <namespace>', 'Kubernetes namespace for --dashboard, --job and --deploy-list.')
+  .option('--dry-run', 'Renders the --dashboard or --job manifests without applying them.')
+  .option('--pod-name <pod-name>', 'Waits for this cluster object to reach --pod-status instead of running tests.')
+  .option('--pod-status <pod-status>', 'Status --pod-name waits for (default: "Running").')
+  .option('--kind-type <kind-type>', 'Kind --pod-name queries (default: "pods").')
+  .description('Runs the test tiers locally, inside deployment pods, or as a cluster Job with Allure reporting.')
+  .action(Underpost.test.callback);
+
 program
   .command('docker-compose')
   .argument('[target]', 'Optional service name for --logs, --shell, --restart, or --build.')
@@ -1138,15 +1313,15 @@ program
   .option('--control <ip>', 'Control-plane IP the worker node joins (used with --worker for kubeadm infra setup).')
   .option(
     '--ssh-key-dir <dir>',
-    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~.',
+    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy/users/<user> for a non-root --user, otherwise engine-private/deploy. Supports a leading ~.',
   )
   .option(
     '--deploy-id <deploy-id>',
-    'Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command.',
+    'Deployment ID used to resolve the private engine repo cloned onto the node (engine-<suffix>-private.',
   )
   .option(
     '--user <user>',
-    'SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user.',
+    'SSH user whose cluster scoped key pair is used (engine-private/deploy/users/<user>/id_rsa) and the login user on an existing control-plane (defaults to root, whose key is engine-private/deploy/id_rsa). Mirrors the ssh command --user.',
   )
   .option(
     '--engine-repo <url>',
@@ -1211,6 +1386,23 @@ program
   )
   .action(Underpost.baremetal.callback);
 
+program
+  .command('package')
+  .argument(
+    '[deploy-id]',
+    'Deploy id, or a comma-separated list, to act on. Defaults to every deploy id in the private configuration tree.',
+  )
+  .option('--sync', 'Regenerates each deploy manifest from the engine manifest and the deploy catalog (default).')
+  .option('--install', 'Installs the dependencies the deploy catalog pins into this checkout.')
+  .option('--rename <name>', "Renames this checkout's package, in its manifest and its lockfile.")
+  .option('--set-repo <owner/repo>', "Points this checkout's package at a repository.")
+  .option('--dry-run', 'For --sync: resolves the manifests without writing them.')
+  .description(
+    "Generates the package manifests a deploy id owns, from the engine manifest and the deploy's " +
+      'product catalog, and installs the dependencies that catalog pins.',
+  )
+  .action(Underpost.package.callback);
+
 program
   .command('release')
   .argument('[version]', 'The new version string to set (e.g., "3.1.4"). Defaults to current version.')