underpost 3.2.80 → 3.3.0

package/src/cli/index.js

@@ -2,7 +2,8 @@ import dotenv from 'dotenv';
 import fs from 'fs-extra';
 
 import { Command } from 'commander';
-import { getNpmRootPath, getUnderpostRootPath, loadConf } from '../server/conf.js';
+import { loadConf } from '../server/conf.js';
+import { getNpmRootPath, getUnderpostRootPath } from '../server/environment.js';
 import { commitData } from '../client/components/core/CommonJs.js';
 
 import Underpost from '../index.js';
@@ -51,6 +52,7 @@ program
   .option('--merge-zip <build-prefix>', 'Merge split ZIP parts back into a single ZIP file for the given build prefix')
   .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')
   .description('Builds client assets, single replicas, and/or syncs environment ports.')
   .action(Underpost.repo.client);
 
@@ -143,7 +145,7 @@ program
     '--switch-repo <url>',
     'Switches the git remote (origin) to <url> and force-pulls the target branch, overwriting the current working tree (discards local commits and tracked changes). Accepts a full URL or "owner/repo".',
   )
-  .option('--target-branch <branch>', 'Target branch for --switch-repo (default: master).')
+  .option('--target-branch <branch>', 'Target branch for --switch-repo (default: remote default branch).')
   .description('Manages commits to a GitHub repository, supporting various commit types and options.')
   .action(Underpost.repo.commit);
 
@@ -254,6 +256,10 @@ program
   .option('--ban-egress-clear', 'Clears all banned egress IP addresses.')
   .option('--ban-both-add', 'Adds IP addresses to both banned ingress and egress lists.')
   .option('--ban-both-remove', 'Removes IP addresses from both banned ingress and egress lists.')
+  .option('--block-all-egress', 'Blocks all outbound traffic from this host (keeps established/related connections).')
+  .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('--mac', 'Prints the MAC address of the main network interface.')
   .description('Displays the current public machine IP addresses.')
   .action(Underpost.dns.ipDispatcher);
@@ -264,7 +270,8 @@ program
   .option('--reset', `Deletes all clusters and prunes all related data and caches.`)
   .option(
     '--reset-mongodb',
-    `Performs a hard cleanup of only MongoDB-related resources (StatefulSet, PVCs/PVs, Secrets, ConfigMaps, caches) without restarting the whole node.`,
+    `Performs a hard cleanup of only MongoDB-related resources (StatefulSet, PVCs/PVs, Secrets, ConfigMaps, caches) without restarting the whole node. ` +
+      `Combined with --mongodb it instead wipes the retained hostPath volumes as part of that deploy, so the replica set starts from empty data.`,
   )
   .option('--mariadb', 'Initializes the cluster with a MariaDB statefulset.')
   .option('--mysql', 'Initializes the cluster with a MySQL statefulset.')
@@ -275,6 +282,16 @@ program
   .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.')
+  .option(
+    '--gateway-api',
+    'Initializes the cluster with the Gateway API control plane (CRDs, Envoy Gateway, GatewayClass) used by generated HTTPRoute + QUIC/HTTP3 manifests. ' +
+      'With --dev the data plane binds the listener ports on the host network for direct browser access.',
+  )
+  .option('--gateway-class <name>', 'GatewayClass name to provision (default "eg").')
+  .option(
+    '--ingress-node <node-name>',
+    'Dedicated node for underpost-ingress when both routing stacks coexist. Workload placement flags do not move it.',
+  )
   .option(
     '--node-port',
     'Exposes enabled ready services (e.g. MongoDB 4.4, Valkey) to the host/public network via their NodePort Service manifest.',
@@ -332,7 +349,6 @@ program
   .option('--remove', 'Deletes specified deployments and their associated services.')
   .option('--sync', 'Synchronizes deployment environment variables, ports, and replica counts.')
   .option('--info-router', 'Displays the current router structure and configuration.')
-  .option('--expose', 'Exposes services matching the provided deployment ID list.')
   .option('--cert', 'Resets TLS/SSL certificate secrets for deployments.')
   .option('--cert-hosts <hosts>', 'Resets TLS/SSL certificate secrets for specified hosts.')
   .option(
@@ -342,6 +358,10 @@ program
       'Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer.',
   )
   .option('--node <node>', 'Sets optional node for deployment operations.')
+  .option(
+    '--ingress-node <node-name>',
+    'Explicitly relocates the shared host-network ingress; ordinary --node placement never moves it.',
+  )
   .option(
     '--ssh-key-path <path>',
     'Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa.',
@@ -350,6 +370,10 @@ program
     '--build-manifest',
     'Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets.',
   )
+  .option(
+    '--sync-static',
+    'Places the SSR status pages and intercepted contexts in the gateway static utility tree, so the edge serves them instead of the application pods. Prefers the running workload and falls back to this checkout, so it can seed the tree before the deployment exists and refresh it once the deployment is Ready.',
+  )
   .option('--replicas <replicas>', 'Sets a custom number of replicas for deployments.')
   .option('--image <image>', 'Sets a custom image for deployments.')
   .option('--versions <deployment-versions>', 'A comma-separated list of custom deployment versions.')
@@ -362,35 +386,31 @@ program
   .option('--retry-count <count>', 'Sets HTTPProxy per-route retry count (e.g., 3).')
   .option('--retry-per-try-timeout <duration>', 'Sets HTTPProxy retry per-try timeout (e.g., "150ms").')
   .option('--disable-update-deployment', 'Disables updates to deployments.')
-  .option('--disable-runtime-probes', 'Omits the internal-status HTTP probes from generated deployment manifests.')
+  .option(
+    '--disable-runtime-probes',
+    'Deprecated compatibility flag; readiness probes remain mandatory. Use --tcp-probes for legacy workloads.',
+  )
   .option('--tcp-probes', 'Generates legacy TCP socket probes instead of HTTP internal-status probes (migration).')
   .option('--disable-update-proxy', 'Disables updates to proxies.')
   .option('--disable-deployment-proxy', 'Disables proxies of deployments.')
-  .option('--disable-update-volume', 'Disables updates to volume mounts during deployment.')
   .option(
-    '--status',
-    'Retrieves current network traffic data from resource deployments and the host machine network configuration.',
+    '--gateway-api',
+    'Routes through the Gateway API stack (Gateway + HTTPRoute) instead of the Contour HTTPProxy. ' +
+      'Both manifest sets are always generated; this selects which one is applied.',
+  )
+  .option('--gateway-class <name>', 'GatewayClass name for generated Gateway manifests (default "eg").')
+  .option(
+    '--disable-http3',
+    '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('--disable-update-volume', 'Disables updates to volume mounts during deployment.')
   .option('--kubeadm', 'Enables the kubeadm context for deployment operations.')
   .option('--k3s', 'Enables the k3s context for deployment operations.')
   .option('--kind', 'Enables the kind context for deployment operations.')
   .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
   .option('--disable-update-underpost-config', 'Disables updates to Underpost configuration during deployment.')
   .option('--namespace <namespace>', 'Kubernetes namespace for deployment operations (defaults to "default").')
-  .option('--kind-type <kind-type>', 'Specifies the Kind cluster type for deployment operations.')
-  .option('--port <port>', 'Sets up port forwarding from local to remote ports.')
-  .option(
-    '--expose-port <port>',
-    'Sets the local:remote port to expose when --expose is active (overrides auto-detected service port).',
-  )
-  .option(
-    '--expose-local-port <port>',
-    'Sets a different local port for --expose (e.g. 80) while keeping the remote service port. Useful for /etc/hosts local access without specifying a port in the browser.',
-  )
-  .option(
-    '--local-proxy',
-    'Forward all service TCP ports locally and start the Node.js path-routing proxy. Enables full path-based routing (e.g. /wp alongside /) without needing --expose-local-port. Requires --expose.',
-  )
   .option('--cmd <cmd>', 'Custom initialization command for deployment (comma-separated commands).')
   .option(
     '--skip-full-build',
@@ -404,30 +424,71 @@ program
     '--image-pull-policy <policy>',
     'Override container imagePullPolicy in the generated deployment manifest (Always, IfNotPresent, Never). Defaults to Never for localhost/ images and IfNotPresent otherwise.',
   )
-  .option(
-    '--tls',
-    'Enables TLS for the local proxy started by --expose --local-proxy. ' +
-      'The proxy will serve HTTPS on port 443 using self-signed certificates resolved from the local SSL store. ' +
-      'Use together with --expose and --local-proxy.',
-  )
   .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(', ')}.`)
+  .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((...args) => {
-    if (args[1].globalClean) return Underpost.secret.globalSecretClean();
-    if (args[1].createFromFile) return Underpost.secret[args[0]].createFromEnvFile(args[1].createFromFile);
-    if (args[1].createFromEnv) return Underpost.secret[args[0]].createFromContainerEnv();
-    if (args[1].list) return Underpost.secret[args[0]].list();
-    if (args[1].init) return Underpost.secret[args[0]].init();
+  .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();
   });
 
 program
@@ -537,19 +598,23 @@ program
 
 program
   .command('cron')
-  .argument('[deploy-list]', 'A comma-separated list of deployment IDs (e.g., "default-a,default-b").')
+  .argument(
+    '[deploy-list]',
+    'A comma-separated list of deployment IDs (e.g., "default-a,default-b"). In manifest modes its first entry is the manifest owner deploy-id.',
+  )
   .argument(
     '[job-list]',
-    `A comma-separated list of job IDs. Options: ${Underpost.cron.getJobsIDs()}. Defaults to all available jobs.`,
+    `A comma-separated list of job IDs. Options: ${Underpost.cron.getJobsIDs()}. Defaults to all available jobs, and restricts which jobs are generated in manifest modes.`,
   )
   .option('--generate-k8s-cronjobs', 'Generates Kubernetes CronJob YAML manifests from cron configuration.')
-  .option('--apply', 'Applies generated K8s CronJob manifests to the cluster via kubectl.')
+  .option('--apply', 'Generates and applies K8s CronJob manifests to the cluster via kubectl (never runs jobs).')
   .option(
-    '--setup-start [deploy-id]',
-    'Updates deploy-id package.json start script and generates+applies its K8s CronJob manifests.',
+    '--setup-start',
+    'Updates deploy-list package.json start script and generates+applies its K8s CronJob manifests.',
   )
   .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('--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.')
@@ -559,7 +624,7 @@ program
   .option('--dry-run', 'Preview cron jobs without executing them.')
   .option(
     '--create-job-now',
-    'After applying manifests, immediately create a Job from each CronJob (requires --apply).',
+    'Creates a Job from each CronJob on the cluster now (implies manifest mode; combine with --apply to publish first).',
   )
   .description('Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests.')
   .action(Underpost.cron.callback);
@@ -641,6 +706,108 @@ program
   .description('Manages SSH credentials and sessions for remote access to cluster nodes or services.')
   .action(Underpost.ssh.callback);
 
+// `underpost wireguard` and `underpost haproxy` are two entrypoints onto one
+// subsystem: the L3 transport and the gateway in front of it are configured from
+// the same deploy state, so they share a single option set and a single action
+// rather than drifting into two half-overlapping command surfaces.
+const edgeCommandFactory = (name, description) =>
+  program
+    .command(name)
+    .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, ' +
+        '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('--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").',
+    )
+    .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-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('--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('--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.')
+    .option(
+      '--status',
+      'Prints the whole edge context without changing anything: role, interface, tunnel address, ' +
+        'public key, daemon states, peers with their bindings and link health, and the resolved routing.',
+    )
+    .option(
+      '--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.',
+    )
+    .option(
+      '--forward-proxy-server',
+      'Ensures the hub HTTP/CONNECT forward proxy runs as the underpost-forward-proxy systemd service, ' +
+        'bound to the tunnel address only (default port 1080), and returns. Authenticates every request with ' +
+        'FORWARD_PROXY_API_KEY, so spokes can reach the internet through the VPS public address. Idempotent: ' +
+        're-running converges on the one service and restarts it only when the unit actually changed.',
+    )
+    .option(
+      '--forward-proxy-server-host <host>',
+      'Address the forward proxy binds, overriding the hub tunnel address from the registry.',
+    )
+    .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.',
+    )
+    .option('--wireguard-start', 'Enables and starts wg-quick@<interface> and the 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('--dry-run', 'Prints the files and commands the run would apply, without touching the host.')
+    .description(description)
+    .action(Underpost.wireguard.callback);
+
+edgeCommandFactory(
+  'wireguard',
+  'Manages the WireGuard L3 hub-and-spoke transport and the HAProxy edge gateway in front of it.',
+);
+edgeCommandFactory(
+  'haproxy',
+  'Manages the HAProxy edge gateway over the WireGuard transport (same subsystem as `underpost wireguard`).',
+);
+
+program
+  .command('vultr')
+  .argument('[deploy-list]', 'A comma-separated list of deployment IDs, logged for attribution.')
+  .option('--instance-id <instance-id>', 'Vultr instance id to meter (default: VULTR_INSTANCE_ID).')
+  .option('--api-key <api-key>', 'Vultr API key (default: VULTR_API_KEY). Prefer the environment over this flag.')
+  .option(
+    '--threshold <ratio>',
+    'Fraction of the plan quota that triggers the egress block; "0.80" and "80" are both accepted (default: 0.80).',
+  )
+  .option('--metric <metric>', '"total" (incoming + outgoing, default) or "outgoing" for egress alone.')
+  .option('--month <yyyy-mm>', 'Billing month to sum (default: the current UTC month).')
+  .option('--all-dates', 'Sum every daily bucket the API returns instead of scoping to one month.')
+  .option('--host <ip>', 'Edge VPS to block (default: VULTR_VPS_IP, then DEFAULT_SSH_HOST).')
+  .option('--user <user>', 'SSH user on the edge VPS (default: VULTR_SSH_USER, then DEFAULT_SSH_USER, then "root").')
+  .option('--key-path <path>', 'SSH private key (default: VULTR_SSH_KEY_PATH, then DEFAULT_SSH_KEY_PATH).')
+  .option('--port <port>', 'SSH port on the edge VPS (default: VULTR_SSH_PORT, then DEFAULT_SSH_PORT, then 22).')
+  .option('--force', 'Re-apply the egress block even if it was already applied for this cycle.')
+  .option('--auto-unblock', 'Restore egress automatically once consumption falls back under the threshold.')
+  .option('--dry-run', 'Reports the consumption and the action it would take, without touching the edge VPS.')
+  .description('Meters the edge VPS bandwidth against its Vultr plan quota and blocks egress before overage accrues.')
+  .action(Underpost.vultr.callback);
+
 program
   .command('run')
   .argument('<runner-id>', `The runner ID to run. Options: ${Underpost.run.RUNNERS}.`)
@@ -652,11 +819,24 @@ program
   .option('--replicas <replicas>', 'Sets a custom number of replicas for deployment.')
   .option('--pod-name <pod-name>', 'Optional: Specifies the pod name for execution.')
   .option('--node-name <node-name>', 'Optional: Specifies the node name for execution.')
+  .option(
+    '--ingress-node <node-name>',
+    'Dedicated node for the host-network underpost-ingress listener. Workload --node-name never relocates it.',
+  )
   .option(
     '--ssh-key-path <path>',
     'Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa.',
   )
   .option('--port <port>', 'Optional: Specifies the port for execution.')
+  .option(
+    '--expose-container-ports <ports>',
+    'Comma-separated Service/container ports; multiple matched resources consume values by resource index.',
+  )
+  .option(
+    '--expose-host-ports <ports>',
+    'Comma-separated host ports paired with container ports by resource/port index.',
+  )
+  .option('--local-proxy', 'Starts the development path proxy after the expose runner creates its port-forwards.')
   .option('--etc-hosts', 'Enables etc-hosts context for the runner execution.')
   .option('--volume-host-path <volume-host-path>', 'Optional: Specifies the volume host path for test execution.')
   .option('--volume-mount-path <volume-mount-path>', 'Optional: Specifies the volume mount path for test execution.')
@@ -692,19 +872,25 @@ program
     '--resource-template-id <resource-template-id >',
     'Specifies a resource template ID for the runner execution.',
   )
-  .option('--expose', 'Enables service exposure for the runner execution.')
+  .option(
+    '--expose',
+    'Enables exposure-only behavior in compatible runners; the expose runner itself does not require this flag.',
+  )
   .option('--conf-server-path <conf-server-path>', 'Sets a custom configuration server path.')
   .option('--underpost-root <underpost-root>', 'Sets a custom Underpost root path.')
   .option('--cmd-cron-jobs <cmd-cron-jobs>', 'Pre-script commands to run before cron job execution.')
   .option(
     '--deploy-id-cron-jobs <deploy-id-cron-jobs>',
-    'Specifies deployment IDs to synchronize cron jobs with during execution.',
+    'Cron deploy-id to set up during sync; defaults to dd.cron, "none" skips cron setup entirely.',
   )
   .option('--timezone <timezone>', 'Sets the timezone for the runner execution.')
   .option('--kubeadm', 'Sets the kubeadm cluster context for the runner execution.')
   .option('--k3s', 'Sets the k3s cluster context for the runner execution.')
   .option('--kind', 'Sets the kind cluster context for the runner execution.')
-  .option('--traffic <traffic>', 'Blue/green traffic colour to bake into generated manifests (default: blue).')
+  .option(
+    '--traffic <traffic>',
+    'Blue/green traffic colour to bake into generated manifests (default: blue). `stop` accepts a comma list, e.g. blue,green.',
+  )
   .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
   .option('--deploy-id <deploy-id>', 'Sets deploy id context for the runner execution.')
   .option('--user <user>', 'Sets user context for the runner execution.')
@@ -718,6 +904,21 @@ program
   .option('--timeout-idle <duration>', 'Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity").')
   .option('--retry-count <count>', 'Sets HTTPProxy per-route retry count (e.g., 3).')
   .option('--retry-per-try-timeout <duration>', 'Sets HTTPProxy retry per-try timeout (e.g., "150ms").')
+  .option(
+    '--gateway-api',
+    'Routes through the Gateway API stack (Gateway + HTTPRoute) instead of the Contour HTTPProxy. ' +
+      'Both manifest sets are always generated; this selects which one is applied.',
+  )
+  .option(
+    '--disable-gateway-api',
+    'Falls back to the Contour HTTPProxy stack in runners where the Gateway API is the default (cluster).',
+  )
+  .option('--gateway-class <name>', 'GatewayClass name for generated Gateway manifests (default "eg").')
+  .option(
+    '--disable-http3',
+    '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('--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").')

package/src/cli/ipfs.js

@@ -6,11 +6,14 @@
 
 import { loggerFactory } from '../server/logger.js';
 import { shellExec } from '../server/process.js';
+import { resolveReplicaCount } from '../server/conf.js';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
 const logger = loggerFactory(import.meta);
 
+const IPFS_DEFAULT_REPLICA_COUNT = 3;
+
 /**
  * @class UnderpostIPFS
  * @description Manages deployment of an ipfs-cluster StatefulSet on Kubernetes.
@@ -25,8 +28,12 @@ class UnderpostIPFS {
      * @description Resolves the IPFS cluster credentials from engine-private/ if they
      * already exist, otherwise generates new ones (hex cluster secret + peer identity
      * via ipfs-cluster-service init) and persists them with mode 0o600.
+     * Idempotent and self-healing: an existing pair is reused untouched, and a missing or
+     * unreadable one is regenerated. Both files are always rewritten together — the peer id and
+     * the private key are two halves of one identity, so reusing one with a freshly minted other
+     * would advertise a peer id that does not match the key.
      * @param {string} privateDir - Absolute path to the engine-private directory.
-     * @returns {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string } }}
+     * @returns {{ CLUSTER_SECRET: string, IDENTITY_JSON: { id: string, private_key: string }, generated: boolean }}
      * @memberof UnderpostIPFS
      */
     resolveCredentials(privateDir) {
@@ -34,11 +41,17 @@ class UnderpostIPFS {
       const identityPath = `${privateDir}/ipfs-cluster-identity.json`;
 
       if (fs.existsSync(secretPath) && fs.existsSync(identityPath)) {
-        logger.info('Reusing existing IPFS cluster credentials from engine-private/');
-        return {
-          CLUSTER_SECRET: fs.readFileSync(secretPath, 'utf8').trim(),
-          IDENTITY_JSON: JSON.parse(fs.readFileSync(identityPath, 'utf8')),
-        };
+        try {
+          const CLUSTER_SECRET = fs.readFileSync(secretPath, 'utf8').trim();
+          const IDENTITY_JSON = JSON.parse(fs.readFileSync(identityPath, 'utf8'));
+          if (CLUSTER_SECRET && IDENTITY_JSON?.id && IDENTITY_JSON?.private_key) {
+            logger.info('Reusing existing IPFS cluster credentials from engine-private/');
+            return { CLUSTER_SECRET, IDENTITY_JSON, generated: false };
+          }
+          logger.warn('Existing IPFS cluster credentials are incomplete; regenerating');
+        } catch (error) {
+          logger.warn(`Existing IPFS cluster credentials are unreadable (${error.message}); regenerating`);
+        }
       }
 
       logger.info('Generating new IPFS cluster credentials and persisting to engine-private/');
@@ -61,7 +74,52 @@ class UnderpostIPFS {
 
       logger.info(`IPFS cluster credentials saved (peer ID: ${IDENTITY_JSON.id})`);
 
-      return { CLUSTER_SECRET, IDENTITY_JSON };
+      return { CLUSTER_SECRET, IDENTITY_JSON, generated: true };
+    },
+
+    /**
+     * @method storeCredentials
+     * @description Encrypts the current IPFS credentials into the SOPS store, replacing whatever
+     * is there. Called after a regeneration so the encrypted Secret cannot drift from the peer id
+     * the `env-config` ConfigMap advertises — the id lives only in the local identity file, so a
+     * stale manifest would pair someone else's private key with the new id and the cluster would
+     * never form.
+     * @param {{ CLUSTER_SECRET: string, IDENTITY_JSON: { private_key: string } }} credentials
+     * @param {object} options
+     * @param {string} options.namespace - Kubernetes namespace.
+     * @memberof UnderpostIPFS
+     */
+    storeCredentials({ CLUSTER_SECRET, IDENTITY_JSON }, options) {
+      const stageDir = '/dev/shm/underpost-secrets';
+      const stagePath = `${stageDir}/ipfs-cluster-secret.yaml`;
+      fs.ensureDirSync(stageDir);
+      fs.chmodSync(stageDir, 0o700);
+      try {
+        fs.outputFileSync(
+          stagePath,
+          [
+            'apiVersion: v1',
+            'kind: Secret',
+            'metadata:',
+            '  name: ipfs-cluster-secret',
+            `  namespace: ${options.namespace}`,
+            '  labels:',
+            '    app.kubernetes.io/managed-by: underpost',
+            'type: Opaque',
+            'stringData:',
+            `  cluster-secret: '${CLUSTER_SECRET.replace(/'/g, "''")}'`,
+            `  bootstrap-peer-priv-key: '${IDENTITY_JSON.private_key.replace(/'/g, "''")}'`,
+            '',
+          ].join('\n'),
+          'utf8',
+        );
+        fs.chmodSync(stagePath, 0o600);
+        // encrypt() stages, validates, moves into place, and shreds the plaintext source.
+        Underpost.secret.sops.encrypt(stagePath, options.namespace, { force: true });
+        logger.info('Re-encrypted regenerated IPFS credentials into the SOPS store');
+      } finally {
+        fs.removeSync(stageDir);
+      }
     },
 
     /**
@@ -100,12 +158,18 @@ class UnderpostIPFS {
     applySecrets({ CLUSTER_SECRET, IDENTITY_JSON }, options) {
       logger.info('Applying IPFS cluster Kubernetes Secret and env ConfigMap');
 
-      shellExec(
-        `kubectl create secret generic ipfs-cluster-secret \
+      // Encrypted store first, origin generate/read logic only when no manifest is stored.
+      // `--from-literal` places the cluster secret and the peer private key in the command
+      // string, so the seed path is kept out of the command log; the encrypted path never
+      // exposes them at all.
+      if (!Underpost.secret.sops.applyIfPresent('ipfs-cluster-secret', options.namespace))
+        shellExec(
+          `kubectl create secret generic ipfs-cluster-secret \
 --from-literal=cluster-secret=${CLUSTER_SECRET} \
 --from-literal=bootstrap-peer-priv-key=${IDENTITY_JSON.private_key} \
 --dry-run=client -o yaml | kubectl apply -f - -n ${options.namespace}`,
-      );
+          { disableLog: true },
+        );
 
       shellExec(
         `kubectl create configmap env-config \
@@ -165,7 +229,14 @@ sudo sysctl -w net.core.wmem_max=7500000`,
 
       const credentials = Underpost.ipfs.resolveCredentials(`${underpostRoot}/engine-private`);
 
-      const ipfsReplicas = options.replicas ? parseInt(options.replicas) : 3;
+      // `env-config` advertises `bootstrap-peer-id` from the local identity file — the peer id is
+      // not carried in the Secret. So a regeneration invalidates any stored manifest: it would
+      // pair the previous private key with the new id and the cluster would never form. Re-encrypt
+      // the fresh pair so the store and the ConfigMap stay one identity.
+      if (credentials.generated && Underpost.secret.sops.has('ipfs-cluster-secret', options.namespace))
+        Underpost.ipfs.storeCredentials(credentials, options);
+
+      const ipfsReplicas = resolveReplicaCount(options.replicas, IPFS_DEFAULT_REPLICA_COUNT);
 
       Underpost.ipfs.teardown(options, ipfsReplicas);
       Underpost.ipfs.applySecrets(credentials, options);

package/src/cli/lxd.js

@@ -5,7 +5,7 @@
  *
  */
 
-import { getNpmRootPath } from '../server/conf.js';
+import { getNpmRootPath } from '../server/environment.js';
 import { pbcopy, shellExec } from '../server/process.js';
 import walk from 'ignore-walk';
 import fs from 'fs-extra';

package/src/cli/monitor.js

@@ -8,10 +8,10 @@ import {
   loadReplicas,
   pathPortAssignmentFactory,
   loadConfServerJson,
-  loadCronDeployEnv,
   etcHostFactory,
   deployRangePortFactory,
 } from '../server/conf.js';
+import { loadCronDeployEnv } from '../server/cron.js';
 import { loggerFactory } from '../server/logger.js';
 import { timer } from '../client/components/core/CommonJs.js';
 import {
@@ -123,7 +123,7 @@ class UnderpostMonitor {
 
       let errorPayloads = [];
       if (options.sync === true) {
-        const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
+        const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace, env });
         if (currentTraffic) Underpost.env.set(`${deployId}-${env}-traffic`, currentTraffic);
       }
       let traffic = Underpost.env.get(`${deployId}-${env}-traffic`) ?? 'blue';