underpost 3.2.80 → 3.2.90

package/src/cli/docker-compose.js

@@ -12,7 +12,6 @@ import fs from 'fs-extra';
 import nodePath from 'path';
 import { getRootDirectory, shellExec } from '../server/process.js';
 import { loggerFactory } from '../server/logger.js';
-import { loadInstanceTopology } from '../server/conf.js';
 import Nginx from '../runtime/nginx/Nginx.js';
 
 const logger = loggerFactory(import.meta);
@@ -82,9 +81,10 @@ class UnderpostDockerCompose {
    * Resolves the canonical directory for a custom docker-compose workflow,
    * keyed by `--deploy-id` + `--docker-compose-id`:
    * `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>`.
-   * This directory ships its own `docker-compose.yml`, `compose.env`, and
-   * `nginx.conf` (used as-is, never generated). Returns null when
-   * `--docker-compose-id` is not set (the default, self-generating workflow).
+   * This directory ships its own `docker-compose.yml`, `compose.env`, and any
+   * project-specific bind-mounted files (all used as-is, never generated).
+   * Returns null when `--docker-compose-id` is not set (the default,
+   * self-generating workflow).
    * @param {object} options - CLI options.
    * @returns {string|null} Repo-root-relative canonical dir, or null.
    * @memberof UnderpostDockerCompose
@@ -100,8 +100,8 @@ class UnderpostDockerCompose {
    * so behavior is independent of the caller's working directory.
    *
    * Custom workflow (`--docker-compose-id`): the compose file, env-file, and
-   * bind-mounted config (nginx.conf, mongodb/) all live in the canonical dir, so
-   * compose runs with `--project-directory` pinned there and no app-override.
+   * project-owned bind-mounted config all live in the canonical dir, so compose
+   * runs with `--project-directory` pinned there and no app-override.
    * @param {object} options - CLI options.
    * @returns {string} The base command string (without a subcommand).
    * @memberof UnderpostDockerCompose
@@ -192,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.80
+APP_TAG=v3.2.90
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest
@@ -362,150 +362,6 @@ datasources:
 `;
   }
 
-  /**
-   * Expands the deploy's `multiInstance` topology (from conf.instances.json, via
-   * {@link loadInstanceTopology}) into the per-variant descriptors the compose
-   * generators consume. Application-agnostic: it only reads variant code/slug/
-   * path and the default code. Returns null when the deploy is single-instance.
-   * @param {object} options - CLI options.
-   * @returns {?{defaultCode: string, variants: Array<object>}}
-   * @memberof UnderpostDockerCompose
-   */
-  static instanceTopology(options = {}) {
-    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
-    let topology = null;
-    try {
-      topology = loadInstanceTopology(deployId);
-    } catch {
-      return null;
-    }
-    if (!topology || !Array.isArray(topology.variants) || topology.variants.length === 0) return null;
-    const defaultCode = topology.default || topology.variants[0].code;
-    const variants = topology.variants.map((v) => {
-      const path = v.path || '/';
-      const isDefault = !(v.slug || '');
-      return {
-        code: v.code,
-        slug: v.slug || '',
-        path,
-        isDefault,
-        // Service/container suffix: empty for the default variant so it keeps
-        // the historic `cyberia-server` / `cyberia-client` names (and their
-        // published host ports); `-forest`, `-test`, … for the rest.
-        suffix: v.slug ? `-${v.slug}` : '',
-        // Backend prefix strip, mirroring the K8s pathRewritePolicy: the Go
-        // server serves `/ws` at its root, so a `/FOREST` prefix is stripped.
-        strip: path !== '/',
-      };
-    });
-    return { defaultCode, variants };
-  }
-
-  /**
-   * Renders the nginx reverse-proxy config for the multi-instance Cyberia stack
-   * as a SINGLE localhost gateway (dev compose is single-host; production uses
-   * the K8s HTTPProxy, not this file). All three tiers share one origin, routed
-   * by URL sub-path so `http://localhost/` works with no /etc/hosts:
-   *   /api/*, /assets/*        -> engine-cyberia (shared content authority)
-   *   /<slug>/ws               -> cyberia-server-<slug>  (prefix stripped; the Go
-   *                               runtime is instance-agnostic, selected by
-   *                               INSTANCE_CODE), and /ws -> the default server
-   *   /<slug>, /               -> cyberia-client-<slug>  (prefix kept; the WASM
-   *                               reads the instance from the URL)
-   * Upstreams resolve lazily through Docker's embedded DNS so a variant that is
-   * briefly down never fails nginx startup. Returns null for single-instance.
-   * @param {object} options - CLI options.
-   * @returns {?string} nginx.conf content, or null.
-   * @memberof UnderpostDockerCompose
-   */
-  static instancesNginxContent(options = {}) {
-    const topology = UnderpostDockerCompose.instanceTopology(options);
-    if (!topology) return null;
-    const { variants } = topology;
-
-    const headers = `            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-            proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection $connection_upgrade;
-            proxy_read_timeout 3600s;`;
-
-    const proxyBlock = (variable, upstream, extra = '') =>
-      `            set ${variable} ${upstream};
-${extra}            proxy_pass http://${variable};
-${headers}`;
-
-    // Websocket tier: /<path>/ws -> server (prefix stripped); default -> = /ws.
-    // Longest-prefix ensures /<path>/ws beats the /<path> client location.
-    const wsLocations = variants
-      .map((v) => {
-        const upstream = `cyberia-server${v.suffix}:8081`;
-        const varName = `$up_server_${v.slug || 'default'}`;
-        if (v.isDefault) return `        location = /ws {\n${proxyBlock(varName, upstream)}\n        }`;
-        return `        location ${v.path}/ws {\n${proxyBlock(
-          varName,
-          upstream,
-          `            rewrite ^${v.path}/(.*)$ /$1 break;\n`,
-        )}\n        }`;
-      })
-      .join('\n\n');
-
-    // Presentation tier: /<path> -> client (prefix kept); default -> catch-all /.
-    const clientLocations = variants
-      .map((v) => {
-        const upstream = `cyberia-client${v.suffix}:8081`;
-        const varName = `$up_client_${v.slug || 'default'}`;
-        if (v.isDefault) return `        location / {\n${proxyBlock(varName, upstream)}\n        }`;
-        return `        location = ${v.path} { return 301 ${v.path}/; }
-        location ${v.path} {\n${proxyBlock(varName, upstream)}\n        }`;
-      })
-      .join('\n\n');
-
-    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
-    return `# Generated by 'underpost docker-compose --generate --deploy-id ${deployId} --docker-compose-id ${options.dockerComposeId || 'cyberia'}' — do not hand-edit.
-# Source of truth: engine-private/conf/${deployId}/conf.instances.json (multiInstance).
-# Single localhost gateway (dev compose). Access http://localhost/ (default),
-# http://localhost/<PATH> per variant. Client origins point back here
-# (compose.env CYBERIA_WS_ORIGIN=ws://localhost, CYBERIA_ENGINE_API_ORIGIN=http://localhost).
-
-map $http_upgrade $connection_upgrade {
-    default upgrade;
-    ''      close;
-}
-
-# Docker embedded DNS: resolve upstream names per request so a variant that is
-# briefly down never fails nginx startup or config reload.
-resolver 127.0.0.11 ipv6=off valid=10s;
-
-proxy_http_version 1.1;
-
-server {
-    listen 80 default_server;
-    server_name localhost 127.0.0.1 _;
-
-        location = /healthz {
-            access_log off;
-            return 200 "ok\\n";
-            add_header Content-Type text/plain;
-        }
-
-        # Shared content authority: REST API + engine-served assets (fonts, ui-icons).
-        location /api/ {
-${proxyBlock('$up_engine', 'engine-cyberia:4005')}
-        }
-
-        location /assets/ {
-${proxyBlock('$up_engine', 'engine-cyberia:4005')}
-        }
-
-${wsLocations}
-
-${clientLocations}
-}
-`;
-  }
-
   /**
    * Renders all dynamic supporting files: the nginx reverse-proxy config (from
    * PROXY_HOSTS), the monitoring configs (Prometheus + Grafana datasource), and
@@ -516,25 +372,17 @@ ${clientLocations}
    * @memberof UnderpostDockerCompose
    */
   static generate(options = {}) {
-    // Custom workflow: docker-compose.yml and compose.env are hand-authored in
-    // the canonical dir and used as-is — do NOT generate them. Only (re)write
-    // the two generated artifacts: the MongoDB entrypoint (replica-set
-    // bootstrap) and, for a multi-instance deploy, nginx.conf (per-variant
-    // sub-path routing derived from the conf.instances.json multiInstance block,
-    // kept in sync with the service tiers hand-authored in docker-compose.yml).
+    // A named custom workflow is fully owned by its canonical directory. The
+    // generic CLI validates the standard entry files but never imports project
+    // modules or generates application-specific nginx, env, or helper content.
     const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
     if (composeIdBase) {
-      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
-      fs.mkdirpSync(nodePath.dirname(mongoEntrypointPath));
-      fs.writeFileSync(mongoEntrypointPath, UnderpostDockerCompose.mongoEntrypointContent(), { mode: 0o755 });
-      logger.info('mongodb entrypoint written (custom workflow)', { path: mongoEntrypointPath });
-
-      const nginx = UnderpostDockerCompose.instancesNginxContent(options);
-      if (nginx) {
-        const nginxPath = UnderpostDockerCompose.resolve(`${composeIdBase}/nginx.conf`);
-        fs.writeFileSync(nginxPath, nginx, 'utf8');
-        logger.info('multi-instance nginx.conf written', { path: nginxPath });
-      }
+      const required = ['docker-compose.yml', 'compose.env'].map((name) =>
+        UnderpostDockerCompose.resolve(`${composeIdBase}/${name}`),
+      );
+      const missing = required.filter((path) => !fs.existsSync(path));
+      if (missing.length) throw new Error(`Custom Docker Compose workflow is missing: ${missing.join(', ')}`);
+      logger.info('custom Docker Compose workflow uses canonical files as-is', { path: composeIdBase });
       return;
     }
 
@@ -644,17 +492,10 @@ ${clientLocations}
       silentOnError: true,
     });
 
-    // Custom workflow: docker-compose.yml and compose.env are hand-authored
-    // source — never prune them. Drop only the generated mongo entrypoint;
-    // nginx.conf is left in place so the mount stays valid and --generate/--up
-    // rewrites it.
+    // A named custom workflow owns every file beneath its canonical directory.
+    // Reset tears down Docker resources but never prunes project-owned files.
     const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
     if (composeIdBase) {
-      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
-      if (fs.existsSync(mongoEntrypointPath)) {
-        fs.removeSync(mongoEntrypointPath);
-        logger.info('removed generated artifact', { path: mongoEntrypointPath });
-      }
       logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
       return;
     }
@@ -699,7 +540,7 @@ ${clientLocations}
      * @param {boolean} [options.shell] - Open an interactive shell in `target` (default: app).
      * @param {string} [options.exec] - General-purpose passthrough docker compose subcommand.
      * @param {string} [options.deployId] - Deployment to run as the app (default: dd-default). `dd-default` self-bootstraps a fresh engine; any other id runs the standard `underpost start` command.
-     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/` (docker-compose.yml + compose.env + nginx.conf, used as-is), skipping nginx/env/app-override generation. Used by the Cyberia MMO ecosystem (`--deploy-id dd-cyberia --docker-compose-id cyberia`).
+     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/` (docker-compose.yml + compose.env, used as-is), skipping nginx/env/app-override generation.
      * @param {string} [options.env] - Deployment environment for non-default deploy ids (default: development).
      * @param {string} [options.composeFile] - Override compose file path.
      * @param {string} [options.envFile] - Override env-file path.

package/src/cli/image.js

@@ -12,6 +12,7 @@ import { loggerFactory } from '../server/logger.js';
 import Underpost from '../index.js';
 import { getNpmRootPath } from '../server/conf.js';
 import { shellExec } from '../server/process.js';
+import { crictlCommandFactory } from '../server/cri.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -225,6 +226,7 @@ class UnderpostImage {
      * @param {object} options - Options for the image retrieval.
      * @param {boolean} options.spec - Whether to retrieve images from the pod specifications.
      * @param {string} options.namespace - Kubernetes namespace to filter pods.
+     * @param {boolean} [options.k3s] - Resolve the CRI endpoint as K3s' embedded containerd.
      * @returns {Array<object>} - Array of objects containing pod names and their corresponding images.
      * @memberof UnderpostImage
      */
@@ -245,10 +247,17 @@ class UnderpostImage {
           }))
           .filter((o) => o.image);
       }
-      const raw = shellExec(node === 'kind-worker' ? `docker exec -i ${node} crictl images` : `crictl images`, {
-        stdout: true,
-        silent: true,
-      });
+      // Outside kind, target the live CRI endpoint explicitly: /etc/crictl.yaml
+      // may still point at a CRI-O socket the host no longer runs.
+      const raw = shellExec(
+        node === 'kind-worker'
+          ? `docker exec -i ${node} crictl images`
+          : crictlCommandFactory('images', options || {}),
+        {
+          stdout: true,
+          silent: true,
+        },
+      );
 
       const heads = raw
         .split(`\n`)[0]
@@ -312,7 +321,7 @@ class UnderpostImage {
         shellExec(`docker exec -i kind-control-plane crictl rmi ${imageName}`);
         shellExec(`docker exec -i kind-worker crictl rmi ${imageName}`);
       } else if (kubeadm === true) {
-        shellExec(`crictl rmi ${imageName}`);
+        shellExec(crictlCommandFactory(`rmi ${imageName}`));
       } else if (k3s === true) {
         shellExec(`sudo k3s ctr images rm ${imageName}`);
       }
@@ -381,7 +390,7 @@ class UnderpostImage {
         shellExec(`docker pull ${image}`);
         shellExec(`sudo kind load docker-image ${image}`);
       } else {
-        shellExec(`sudo crictl pull ${image}`);
+        shellExec(crictlCommandFactory(`pull ${image}`, { k3s: targetK3s }));
       }
     },
   };

package/src/cli/index.js

@@ -264,7 +264,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 +276,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 +343,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 +352,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 +364,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 +380,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 +418,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
@@ -652,11 +707,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,7 +760,10 @@ 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.')
@@ -704,7 +775,10 @@ program
   .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 +792,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").')