@underpostnet/cyberia 3.2.90 → 3.3.0

package/src/cli/deploy.js

@@ -10,7 +10,6 @@ import {
   buildProxyRouter,
   clusterTypeFactory,
   Config,
-  cronDeployIdResolve,
   deployHostsFactory,
   deployRangePortFactory,
   gatewayApiEnabledFactory,
@@ -24,8 +23,11 @@ import {
   schedulableNodeFactory,
   trafficFromRoutingInfoFactory,
 } from '../server/conf.js';
+import { cronDeployIdResolve } from '../server/cron.js';
 import { loggerFactory } from '../server/logger.js';
+import { HOST_VOLUME_ROOT } from '../server/environment.js';
 import { shellExec } from '../server/process.js';
+import { runSELinuxCommands, selinuxRestoreconCommandFactory } from '../server/selinux.js';
 import { INTERNAL_READY_PATH, INTERNAL_HEALTH_PATH } from '../server/runtime-status.js';
 import { staticContextRoutesFactory, statusPageRoutesFactory } from '../client-builder/client-build.js';
 import {
@@ -152,6 +154,13 @@ const gatewayDurationFactory = (value) => {
 
 const logger = loggerFactory(import.meta);
 
+// hostPath volume trees are written under the operator's home directory, which
+// carries a label no unprivileged container can read. Cluster bring-up registers
+// the persistent mapping for HOST_VOLUME_ROOT; this applies it to what a deploy
+// just wrote. A no-op where SELinux or its userspace is absent.
+const restoreContainerContext = (path) =>
+  runSELinuxCommands([selinuxRestoreconCommandFactory(path)], { execute: shellExec });
+
 /**
  * @class UnderpostDeploy
  * @description Manages the deployment of applications and services.
@@ -724,7 +733,7 @@ ${Underpost.deploy
               if (!volume.claimName) continue;
               const pvcId = `${volume.claimName}-${deployId}-${env}-${deploymentVersion}`;
               const pvId = pvcId.replace(/^pvc-/, 'pv-');
-              const hostPath = `/home/dd/engine/volume/${pvId}`;
+              const hostPath = `${HOST_VOLUME_ROOT}/${pvId}`;
               volumeYaml += `---\n${Underpost.deploy.persistentVolumeFactory({
                 pvcId,
                 namespace: options.namespace,
@@ -1697,13 +1706,13 @@ ${rules}`;
 
     /**
      * Node directory backing the static utility's volume, following the same
-     * `/home/dd/engine/volume/<pv>` convention as every other hostPath volume.
+     * `HOST_VOLUME_ROOT/<pv>` convention as every other hostPath volume.
      * @param {object} [options] - Deploy/run options.
      * @returns {string} Absolute host path.
      * @memberof UnderpostDeploy
      */
     underpostGatewayRootFactory(options = {}) {
-      return options.underpostGatewayRoot || `/home/dd/engine/volume/${UNDERPOST_GATEWAY.volumeName}`;
+      return options.underpostGatewayRoot || `${HOST_VOLUME_ROOT}/${UNDERPOST_GATEWAY.volumeName}`;
     },
 
     /**
@@ -1881,6 +1890,12 @@ ${rules}`;
               ? 'project'
               : null,
           });
+      // The documents were just written under the operator's home tree, whose
+      // policy label (user_home_t) the unprivileged gateway container cannot
+      // read — it would answer 403 for every one of them. The persistent
+      // mapping is registered at cluster bring-up; restore it here so files
+      // this pass created carry it too.
+      restoreContainerContext(hostRoot);
       logger.info('Static edge documents placed', {
         deployId,
         podName: podName || '(no running workload; placed from this checkout)',
@@ -2632,7 +2647,7 @@ EOF`);
       const clusterContext = options.clusterContext || 'kind';
       const pvcId = `${volume.claimName}-${deployId}-${env}-${version}`;
       const pvId = `${volume.claimName.replace('pvc-', 'pv-')}-${deployId}-${env}-${version}`;
-      const rootVolumeHostPath = `/home/dd/engine/volume/${pvId}`;
+      const rootVolumeHostPath = `${HOST_VOLUME_ROOT}/${pvId}`;
       if (options.gitClean && volume.volumeMountPath) {
         Underpost.repo.clean({ paths: [volume.volumeMountPath] });
       }
@@ -2656,6 +2671,7 @@ EOF`);
           // Target node is the control plane / current host: write directly.
           if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
           fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
+          restoreContainerContext(rootVolumeHostPath);
         } else {
           // Target node is remote: fs.copySync would only write the control-plane
           // filesystem, leaving the real node's hostPath empty. Ship the folder to

package/src/cli/docker-compose.js

@@ -192,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.90
+APP_TAG=v3.3.0
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest

package/src/cli/env.js

@@ -4,7 +4,7 @@
  * @namespace UnderpostEnv
  */
 
-import { getNpmRootPath, writeEnv } from '../server/conf.js';
+import { getNpmRootPath, writeEnv } from '../server/environment.js';
 import fs from 'fs-extra';
 import { loggerFactory } from '../server/logger.js';
 import dotenv from 'dotenv';

package/src/cli/image.js

@@ -10,7 +10,6 @@ import nodePath from 'path';
 import crypto from 'crypto';
 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';
 

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);
@@ -592,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.')
@@ -614,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);
@@ -696,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}.`)
@@ -769,7 +881,7 @@ program
   .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.')

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 {

package/src/cli/release.js

@@ -56,6 +56,10 @@ const buildVersionBumpTargets = () => [
     file: 'src/index.js',
     patterns: /(static version = ['"]v)\d+\.\d+\.\d+(?=['"])/g,
   },
+  {
+    file: 'src/cli/run.js',
+    patterns: /(const version = ['"]v)\d+\.\d+\.\d+(?=['"])/g,
+  },
 
   // ── README + CLI-HELP fallbacks. CLI-HELP is regenerated by `deploy cli-docs`, but bump
   //    it too so the file is consistent if the regeneration step is skipped. ──
@@ -107,6 +111,14 @@ const buildVersionBumpTargets = () => [
     recursive: true,
   },
 
+  // ── Deployment runner scripts carry image defaults passed to deploy/sync commands. ──
+  {
+    dir: 'deploy',
+    match: /\.sh$/,
+    patterns: /(underpost\/[a-z0-9-]+:v)\d+\.\d+\.\d+/g,
+    recursive: true,
+  },
+
   // ── GitHub Actions workflows. Single sweep across docker-image.*.ci.yml, engine-*.cd.yml,
   //    and the root docker-image.ci.yml — replaces previous three separate loops. ──
   {
@@ -261,6 +273,19 @@ const bumpAuxiliaryFiles = (oldVersion, newVersion, { dryRun = false } = {}) =>
   return report;
 };
 
+/**
+ * Returns whether a manifest's canonical top-level version would change. Used by dry-runs
+ * because bumpp has no non-mutating API option.
+ */
+const wouldBumpManifestVersion = (filePath, newVersion) => {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return typeof manifest.version === 'string' && manifest.version !== newVersion;
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Prints a per-file change summary table.
  */
@@ -379,8 +404,8 @@ class UnderpostRelease {
      * 1. Loads production env and pulls latest code; kills dev servers on ports 4001-4003.
      * 2. Builds and smoke-tests the pwa-microservices-template (aborts on error).
      * 3. Canonical version files: delegates to `bumpp` (driven by `bump.config.js`). Bumps
-     *    package.json, package-lock.json (root + packages['']), and every
-     *    engine-private/conf/**\/package.json.
+     *    package.json, package-lock.json (root + packages['']), Hardhat's package metadata,
+     *    and every engine-private/conf/**\/package.json.
      * 4. Auxiliary files: anchored-regex walker over VERSION_BUMP_TARGETS — covers
      *    src/index.js, README, cyberia-docs, nexodev docs, manifests (deployment + cronjobs),
      *    .github/workflows (image tags, type=raw, UNDERPOST_VERSION build-args), and
@@ -420,26 +445,36 @@ class UnderpostRelease {
         if (!templateOk) return;
       }
 
-      // ── Canonical version files: delegate to bumpp (package.json, package-lock.json,
-      //    engine-private/conf/**/package.json). bumpp owns lockfile semantics (root version
-      //    + packages[''].version) so we don't reimplement them. ──
-      const { versionBump } = await import('bumpp');
-      const bumppResult = await versionBump({
-        release: newVersion,
-        files: [
-          'package.json',
-          'package-lock.json',
-          ...(fs.existsSync('./engine-private/conf') ? ['engine-private/conf/**/package.json'] : []),
-        ],
-        commit: false,
-        tag: false,
-        push: false,
-        confirm: false,
-        recursive: false,
-        ignoreScripts: true,
-        dry: dryRun,
-      });
-      logger.info(`bumpp updated ${bumppResult?.files?.length ?? 0} canonical file(s).`);
+      // ── Canonical version files: bumpp owns lockfile semantics (root version +
+      //    packages[''].version). Its API has no non-mutating dry-run, so previews inspect
+      //    manifest versions directly rather than invoking it. ──
+      const canonicalVersionFiles = [
+        'package.json',
+        'package-lock.json',
+        'hardhat/package.json',
+        'hardhat/package-lock.json',
+        ...walkDir('engine-private/conf', /^package\.json$/, true),
+      ];
+      if (dryRun) {
+        const pendingCanonicalFiles = canonicalVersionFiles.filter((file) =>
+          wouldBumpManifestVersion(file, newVersion),
+        );
+        logger.info(`bumpp would update ${pendingCanonicalFiles.length} canonical file(s).`);
+        for (const file of pendingCanonicalFiles) console.log(`  ${file}`);
+      } else {
+        const { versionBump } = await import('bumpp');
+        const bumppResult = await versionBump({
+          release: newVersion,
+          files: canonicalVersionFiles,
+          commit: false,
+          tag: false,
+          push: false,
+          confirm: false,
+          recursive: false,
+          ignoreScripts: true,
+        });
+        logger.info(`bumpp updated ${bumppResult?.updatedFiles?.length ?? 0} canonical file(s).`);
+      }
 
       // ── Auxiliary files: anchored-regex walker over VERSION_BUMP_TARGETS. ──
       const report = bumpAuxiliaryFiles(version, newVersion, { dryRun });

package/src/cli/repository.js

@@ -11,7 +11,6 @@ import { actionInitLog, loggerFactory } from '../server/logger.js';
 import path from 'path';
 import fs from 'fs-extra';
 import {
-  getNpmRootPath,
   Config,
   loadConf,
   readConfJson,
@@ -20,9 +19,9 @@ import {
   loadConfServerJson,
   getDataDeploy,
   buildReplicaId,
-  writeEnv,
   readConfInstances,
 } from '../server/conf.js';
+import { getNpmRootPath, writeEnv } from '../server/environment.js';
 import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../client-builder/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
@@ -109,7 +108,7 @@ class UnderpostRepository {
      * @param {boolean} [options.changelogNoHash=false] - If true, omits commit hashes from the changelog entries.
      * @param {boolean} [options.remoteUrl=false] - If true, prints the current git remote URL (origin) in plain text and returns.
      * @param {string} [options.switchRepo=''] - If set, switches the remote `origin` to this URL and force-pulls the target branch, overwriting the current working tree.
-     * @param {string} [options.targetBranch=''] - Target branch for `switchRepo` (defaults to `master`).
+     * @param {string} [options.targetBranch=''] - Target branch for `switchRepo` (defaults to the remote's default branch).
      * @memberof UnderpostRepository
      */
     commit(
@@ -181,7 +180,7 @@ class UnderpostRepository {
         Underpost.repo.switchRemote({
           path: repoPath,
           url: options.switchRepo,
-          branch: options.targetBranch || 'master',
+          branch: options.targetBranch,
         });
         return;
       }
@@ -906,6 +905,7 @@ class UnderpostRepository {
               split: options.split || '',
               fullBuild: options.liteBuild ? false : true,
               iconsBuild: options.iconsBuild || false,
+              ssrOnly: options.ssr || false,
             });
             for (const replicaDeployId of deployIdSingleReplicas) {
               if (!fs.existsSync(`./engine-private/replica/${replicaDeployId}`)) {
@@ -917,6 +917,7 @@ class UnderpostRepository {
                 split: options.split || '',
                 liteBuild: options.liteBuild || false,
                 iconsBuild: options.iconsBuild || false,
+                ssr: options.ssr || false,
               });
             }
 
@@ -1428,14 +1429,15 @@ Prevent build private config repo.`,
      * @param {object} opts
      * @param {string} opts.url - New remote URL (full URL or "owner/repo" short form).
      * @param {string} [opts.path='.'] - Path to the git repository.
-     * @param {string} [opts.branch='master'] - Target branch to overwrite the current tree with.
+     * @param {string} [opts.branch] - Target branch to overwrite the current tree with. Defaults to the remote's default branch.
      * @param {string} [opts.remote='origin'] - Remote name to set and fetch from.
      * @returns {void}
      * @memberof UnderpostRepository
      */
-    switchRemote({ url, path: repoPath = '.', branch = 'master', remote = 'origin' }) {
+    switchRemote({ url, path: repoPath = '.', branch = '', remote = 'origin' }) {
       if (!url) throw new Error('switchRemote requires a target remote url');
       if (!fs.existsSync(`${repoPath}/.git`)) throw new Error(`switchRemote: not a git repository: ${repoPath}`);
+      const targetBranch = branch || Underpost.repo.getDefaultBranch(url);
       // Token-free URL for the stored remote; auth-injected URL only for the fetch.
       let normalized = url;
       if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('git@')) {
@@ -1445,12 +1447,12 @@ Prevent build private config repo.`,
       const current = Underpost.repo.getRemoteUrl({ path: repoPath, remote });
       if (!current) shellExec(`cd "${repoPath}" && git remote add ${remote} "${normalized}"`);
       else shellExec(`cd "${repoPath}" && git remote set-url ${remote} "${normalized}"`);
-      logger.info('switchRemote', { path: repoPath, remote, branch, url: normalized });
-      shellExec(`cd "${repoPath}" && GIT_TERMINAL_PROMPT=0 git fetch --force "${authUrl}" ${branch}`);
+      logger.info('switchRemote', { path: repoPath, remote, branch: targetBranch, url: normalized });
+      shellExec(`cd "${repoPath}" && GIT_TERMINAL_PROMPT=0 git fetch --force "${authUrl}" ${targetBranch}`);
       // reset --hard first clears the worktree so the checkout cannot be blocked
       // by conflicting local changes; -B points the target branch at the fetched tip.
       shellExec(`cd "${repoPath}" && git reset --hard FETCH_HEAD`);
-      shellExec(`cd "${repoPath}" && git checkout -B ${branch} FETCH_HEAD`);
+      shellExec(`cd "${repoPath}" && git checkout -B ${targetBranch} FETCH_HEAD`);
     },
 
     /**

package/src/cli/run.js

@@ -4,13 +4,12 @@
  * @namespace UnderpostRun
  */
 
-import { daemonProcess, getTerminalPid, pbcopy, shellCd, shellExec } from '../server/process.js';
+import { daemonProcess, pbcopy, shellCd, shellExec } from '../server/process.js';
 import {
   awaitDeployMonitor,
   buildKindPorts,
   clusterContextFactory,
   clusterTypeFactory,
-  cronDeployIdResolve,
   dispatchBuildInstanceEnv,
   deployHostsFactory,
   etcHostFactory,
@@ -21,7 +20,6 @@ import {
   exposeTcpPortsFactory,
   gatewayApiEnabledFactory,
   generateSecurePassword,
-  getNpmRootPath,
   instanceHttpRouteRulesFactory,
   instanceInterceptStatusesFactory,
   instancePortFactory,
@@ -36,7 +34,6 @@ import {
   resolveEnvScoped,
   selectConfInstances,
   waitForPort,
-  writeEnv,
   clusterInstancesFactory,
   deployTrafficEntriesFactory,
   curlStatusChainFactory,
@@ -49,6 +46,8 @@ import {
   stopPlanFactory,
   trafficFromRoutingInfoFactory,
 } from '../server/conf.js';
+import { cronDeployIdResolve } from '../server/cron.js';
+import { getNpmRootPath, writeEnv } from '../server/environment.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 
 import fs from 'fs-extra';
@@ -127,7 +126,7 @@ const logger = loggerFactory(import.meta);
  * @property {string} confServerPath - The configuration server path.
  * @property {string} underpostRoot - The root path of the Underpost installation.
  * @property {string} cmdCronJobs - Pre-script commands to run before cron job execution.
- * @property {string} deployIdCronJobs - The deployment ID for cron jobs.
+ * @property {string} deployIdCronJobs - Cron deploy-id passed to `cron --setup-start`; unset resolves dd.cron, `none` skips cron setup.
  * @property {string} timezone - The timezone to set.
  * @property {boolean} kubeadm - Whether to run in kubeadm mode.
  * @property {boolean} kind - Whether to run in kind mode.
@@ -1172,8 +1171,16 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           if (!validVersion) throw new Error('Version mismatch');
         }
         if (options.timezone !== 'none') shellExec(`${baseCommand} run${baseClusterCommand} tz`);
-        if (options.deployIdCronJobs !== 'none')
-          shellExec(`node bin cron${baseClusterCommand}${clusterFlag} --setup-start --git --apply`);
+        if (options.deployIdCronJobs !== 'none') {
+          // --deploy-id-cron-jobs overrides the cron deploy-id; unset falls back to
+          // dd.cron, the same source `cron --setup-start` resolves against on its own.
+          const cronDeployId = options.deployIdCronJobs || cronDeployIdResolve() || '';
+          if (cronDeployId && !/^[a-zA-Z0-9._,-]+$/.test(cronDeployId))
+            throw new Error(`Invalid cron deploy-id: ${cronDeployId}`);
+          shellExec(
+            `node bin cron${cronDeployId ? ` ${cronDeployId}` : ''}${baseClusterCommand}${clusterFlag} --setup-start --git --apply`,
+          );
+        }
       }
 
       const currentTraffic = isDeployRunnerContext(path, options)
@@ -1220,7 +1227,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       // runner. Build the host-side SSR documents before generating routes unless
       // the caller explicitly selected a pre-built bundle workflow.
       if (isDeployRunnerContext(path, options) && !options.skipFullBuild)
-        shellExec(`${baseCommand} client ${deployId} ${env}`);
+        shellExec(`${baseCommand} client ${deployId} ${env} --ssr`);
 
       shellExec(
         `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
@@ -3090,7 +3097,7 @@ EOF`);
         const hostListenResult = etcHostFactory(hosts);
         logger.info(hostListenResult.renderHosts);
       }
-      const version = 'v3.2.90';
+      const version = 'v3.3.0';
       const instanceOptionsFactory = (deployId, instanceId) => ({
         ...options,
         ...clusterContextFactory(clusterType),
@@ -4906,6 +4913,26 @@ EOF`;
       }
     },
 
+    /**
+     * @method kubeadm-wireguard
+     * @description
+     * Configures Calico to keep using the Kubernetes NodeInternalIP after WireGuard
+     * is added to the node. This prevents the WireGuard interface (for example
+     * 10.0.0.2) from being selected as the Calico/BGP node address.
+     *
+     * @param {string} path - Unused.
+     * @param {UnderpostRunDefaultOptions} options - The default underpost runner options.
+     * @memberof UnderpostRun
+     */
+    'kubeadm-wireguard': (path, options = DEFAULT_OPTION) => {
+      shellExec(`kubectl patch installation.operator.tigera.io default --type='json' \
+-p='[
+  {"op":"replace","path":"/spec/calicoNetwork/nodeAddressAutodetectionV4","value":{"kubernetes":"NodeInternalIP"}}
+]'`);
+
+      shellExec(`kubectl rollout restart daemonset/calico-node -n calico-system`);
+    },
+
     /**
      * @method build-cluster-deployment-manifests
      * @description Builds deployment manifests for both production and development environments using `node bin deploy --build-manifest`, syncing them, and setting replicas to 1 for the `dd` deployment.