underpost 3.2.22 → 3.2.30

package/src/cli/fs.js

@@ -95,6 +95,17 @@ class UnderpostFileStorage {
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
 
+      // ── Single-file handling: when path is a file (not a directory), use parent dir
+      //    as the git working directory and process just that one file. ──────────────
+      let isSingleFile = false;
+      let parentDir = path;
+      let singleFileName = '';
+      if (fs.existsSync(path) && !fs.statSync(path).isDirectory()) {
+        isSingleFile = true;
+        parentDir = dir.dirname(path);
+        singleFileName = path.split('/').pop();
+      }
+
       // In recursive remove mode, delete every tracked storage key under the requested path,
       // even when local files/directories are already missing.
       if (options.rm === true) {
@@ -137,10 +148,15 @@ class UnderpostFileStorage {
         return;
       }
 
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
+      // For single files, run getDeleteFiles against the parent directory to avoid
+      // trying to `cd` into a file.
+      const gitContextPath = isSingleFile ? parentDir : path;
+      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(gitContextPath);
+
+      // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
-        const _path = path + '/' + relativePath;
-        if (_path in storage) {
+        const _path = isSingleFile ? (relativePath === singleFileName ? path : null) : path + '/' + relativePath;
+        if (_path && _path in storage) {
           await Underpost.fs.delete(_path);
           delete storage[_path];
         }
@@ -157,17 +173,25 @@ class UnderpostFileStorage {
         // Only run git init/commit when the caller explicitly requests git tracking (--git flag).
         // For bundle pulls into ./build the git step is unwanted and would error on a non-repo path.
         if (options.git === true) {
-          Underpost.repo.initLocalRepo({ path });
-          shellExec(`cd ${path} && git add . && git commit -m "Base pull state"`, {
+          Underpost.repo.initLocalRepo({ path: gitContextPath });
+          shellExec(`cd ${gitContextPath} && git add . && git commit -m "Base pull state"`, {
             silentOnError: true,
           });
         }
       } else {
-        const files =
-          options.git === true ? Underpost.repo.getChangedFiles(path) : await fs.readdir(path, { recursive: true });
+        let files;
+        if (isSingleFile) {
+          // Single file: treat the file itself as the sole item to process
+          files = [singleFileName];
+        } else {
+          files =
+            options.git === true
+              ? Underpost.repo.getChangedFiles(gitContextPath)
+              : await fs.readdir(path, { recursive: true });
+        }
         for (const relativePath of files) {
-          const _path = path + '/' + relativePath;
-          if (fs.statSync(_path).isDirectory()) {
+          const _path = isSingleFile ? path : path + '/' + relativePath;
+          if (fs.existsSync(_path) && fs.statSync(_path).isDirectory()) {
             if (options.pull === true && !fs.existsSync(_path)) fs.mkdirSync(_path, { recursive: true });
             continue;
           } else if (!(_path in storage) || options.force === true) {
@@ -178,8 +202,8 @@ class UnderpostFileStorage {
       }
       Underpost.fs.writeStorageConf(storage, storageConf);
       if (options.git === true) {
-        shellExec(`cd ${path} && git add .`);
-        shellExec(`underpost cmt ${path} feat`, {
+        shellExec(`cd ${gitContextPath} && git add .`);
+        shellExec(`underpost cmt ${gitContextPath} feat`, {
           silentOnError: true,
           silent: true,
           disableLog: true,

package/src/cli/index.js

@@ -132,6 +132,12 @@ program
     '--has-changes',
     'Prints "1" if there are staged or unstaged git changes in the repository, empty string otherwise.',
   )
+  .option('--remote-url', 'Prints the current git remote URL (origin) in plain text.')
+  .option(
+    '--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).')
   .description('Manages commits to a GitHub repository, supporting various commit types and options.')
   .action(Underpost.repo.commit);
 
@@ -330,6 +336,10 @@ program
       'Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer.',
   )
   .option('--node <node>', 'Sets optional node for deployment operations.')
+  .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.',
+  )
   .option(
     '--build-manifest',
     'Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets.',
@@ -630,6 +640,10 @@ 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(
+    '--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('--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.')
@@ -738,6 +752,37 @@ program
   .description('Runs specified scripts using various runners.')
   .action(Underpost.run.callback);
 
+program
+  .command('docker-compose')
+  .argument('[target]', 'Optional service name for --logs, --shell, --restart, or --build.')
+  .option('--install', 'Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts.')
+  .option(
+    '--reset',
+    'Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts.',
+  )
+  .option('--force', 'Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset).')
+  .option(
+    '--deploy-id <deploy-id>',
+    "Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js).",
+  )
+  .option('--env <env>', 'Deployment environment for non-default deploy ids (default: development).')
+  .option('--generate', 'Render dynamic supporting files (nginx router config, env-file, app-command override).')
+  .option('--up', 'Start the full stack detached (regenerates config first).')
+  .option('--down', 'Stop and remove containers (and orphans).')
+  .option('--volumes', 'With --down, also remove named volumes (destroys persisted data).')
+  .option('--restart', 'Restart services (optionally a single [target]).')
+  .option('--build', 'With --up rebuild images; alone, rebuilds images with --no-cache.')
+  .option('--pull', 'Pull upstream images for all services.')
+  .option('--logs', 'Follow logs for all services (optionally a single [target]).')
+  .option('--status', 'Show a formatted status table of services.')
+  .option('--shell', 'Open an interactive shell in [target] (default: app).')
+  .option('--exec <subcommand>', 'General-purpose passthrough docker compose subcommand.')
+  .option('--compose-file <path>', 'Path to the compose file (default: docker-compose.yml).')
+  .option('--env-file <path>', 'Path to the compose env-file (default: docker/compose.env).')
+  .option('--nginx-conf <path>', 'Path to the generated nginx config (default: docker/nginx/default.conf).')
+  .description('General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack).')
+  .action(Underpost.dockerCompose.callback);
+
 program
   .command('lxd')
   .argument(
@@ -856,6 +901,42 @@ program
   .option('--remove-machines <system-ids>', 'Removes baremetal machines by comma-separated system IDs, or use "all"')
   .option('--clear-discovered', 'Clears all discovered baremetal machines from the database.')
   .option('--commission', 'Init workflow for commissioning a physical machine.')
+  .option(
+    '--install-disk [device]',
+    'Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk.',
+  )
+  .option(
+    '--no-auto-install',
+    'Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install).',
+  )
+  .option('--no-remote-install', 'Skips the controller-side remote install orchestration over SSH.')
+  .option(
+    '--worker',
+    'Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane.',
+  )
+  .option('--control <ip>', 'Control-plane IP the worker node joins (used with --worker for kubeadm infra setup).')
+  .option(
+    '--ssh-key-dir <dir>',
+    'Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~.',
+  )
+  .option(
+    '--deploy-id <deploy-id>',
+    'Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command.',
+  )
+  .option(
+    '--user <user>',
+    'SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user.',
+  )
+  .option(
+    '--engine-repo <url>',
+    'Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine).',
+  )
+  .option('--engine-branch <branch>', 'Branch of the engine repo to clone on the node.')
+  .option(
+    '--engine-private-repo <url>',
+    'Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private).',
+  )
+  .option('--engine-private-branch <branch>', 'Branch of the engine-private repo to clone on the node.')
   .option(
     '--bootstrap-http-server-run',
     'Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning.',
@@ -896,6 +977,14 @@ program
   )
   .option('--dev', 'Sets the development context environment for baremetal operations.')
   .option('--ls', 'Lists available boot resources and machines.')
+  .option(
+    '--resume-infra-setup',
+    'Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH.',
+  )
+  .option(
+    '--resume-join',
+    'Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join.',
+  )
   .description(
     'Manages baremetal server operations, including installation, database setup, commissioning, and user management.',
   )

package/src/cli/kickstart.js

@@ -43,46 +43,168 @@ class UnderpostKickStart {
 
     /**
      * @method kickstartPreVariables
-     * @description Generates the variable assignments block for the %pre script.
-     * @param {object} options
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
-     * @param {string} [options.adminUsername]
+     * @description Generates the shell variable-assignment block injected at the top of the
+     * kickstart `%pre` script. These variables drive both the ephemeral commissioning runtime
+     * and the unattended disk installer in `scripts/rocky-kickstart.sh`. Passwords are emitted
+     * base64-encoded (`*_B64`) and decoded by an in-script `ks_b64d` helper; all other values
+     * are single-quote escaped so arbitrary content survives the shell/heredoc layers.
+     * @param {object} options - Variable values to bake into the `%pre` block.
+     * @param {string} [options.rootPassword=''] - root console password (base64-encoded).
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user (defaults to MAAS_ADMIN_USERNAME).
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.timezone=''] - IANA timezone configured in the deployed OS (e.g. America/Santiago).
+     * @param {string} [options.keyboardLayout=''] - Console/X11 keyboard layout for the deployed OS (e.g. es).
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server for this host (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk (e.g. /dev/nvme0n1); empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the ephemeral runtime self-installs after a fallback timeout if no remote trigger arrives.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} Newline-joined bash variable assignments.
      */
-    kickstartPreVariables: ({ rootPassword = '', authorizedKeys = '', adminUsername = '' }) => {
+    kickstartPreVariables: ({
+      rootPassword = '',
+      authorizedKeys = '',
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
+      timezone = '',
+      keyboardLayout = '',
+      chronyConfPath = '/etc/chrony.conf',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
+    }) => {
       const sanitizedKeys = (authorizedKeys || '').trim();
+      // Passwords are passed base64-encoded so arbitrary characters (quotes,
+      // spaces, $, etc.) survive every shell/heredoc layer intact. base64 output
+      // never contains single quotes. Decoding tries `base64` then falls back to
+      // python3 so a minimal Anaconda environment can never yield empty passwords.
+      const b64 = (v) => Buffer.from(String(v || ''), 'utf8').toString('base64');
+      const sq = (v) => `'${String(v || '').replace(/'/g, "'\\''")}'`;
       return [
-        `ROOT_PASS='${rootPassword || ''}'`,
-        `AUTHORIZED_KEYS='${sanitizedKeys}'`,
-        `ADMIN_USER='${adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas'}'`,
+        `ks_b64d() { printf %s "$1" | base64 -d 2>/dev/null || printf %s "$1" | python3 -c 'import sys,base64;sys.stdout.buffer.write(base64.b64decode(sys.stdin.read().strip()))' 2>/dev/null; }`,
+        `ROOT_PASS_B64='${b64(rootPassword)}'`,
+        `ADMIN_PASS_B64='${b64(adminPassword || rootPassword)}'`,
+        `DEPLOY_PASS_B64='${b64(deployPassword)}'`,
+        `ROOT_PASS="$(ks_b64d "$ROOT_PASS_B64")"`,
+        `ADMIN_PASS="$(ks_b64d "$ADMIN_PASS_B64")"`,
+        `DEPLOY_PASS="$(ks_b64d "$DEPLOY_PASS_B64")"`,
+        `AUTHORIZED_KEYS=${sq(sanitizedKeys)}`,
+        `ADMIN_USER=${sq(adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas')}`,
+        `DEPLOY_USER=${sq(deployUsername)}`,
+        `NET_IP=${sq(netIp)}`,
+        `NET_PREFIX='${parseInt(netPrefix, 10) || 24}'`,
+        `NET_GATEWAY=${sq(netGateway)}`,
+        `NET_DNS=${sq(netDns)}`,
+        `TIMEZONE=${sq(timezone)}`,
+        `KEYBOARD_LAYOUT=${sq(keyboardLayout)}`,
+        `CHRONY_CONF_PATH=${sq(chronyConfPath || '/etc/chrony.conf')}`,
+        `BOOTSTRAP_URL=${sq(bootstrapUrl)}`,
+        `WORKFLOW_ID=${sq(workflowId)}`,
+        `SYSTEM_ID=${sq(systemId)}`,
+        `TARGET_HOSTNAME=${sq(targetHostname)}`,
+        `SSH_PORT='${sshPort || 22}'`,
+        `INSTALL_DISK_HINT=${sq(installDiskHint)}`,
+        `AUTO_INSTALL='${autoInstall ? '1' : '0'}'`,
       ].join('\n');
     },
 
     /**
      * @method kickstartFactory
      * @description Generates a complete kickstart configuration by combining the header,
-     * variable assignments, and the rocky-kickstart.sh script body.
-     * @param {object} options
-     * @param {string} [options.lang='en_US.UTF-8']
-     * @param {string} [options.keyboard='us']
-     * @param {string} [options.timezone='America/New_York']
-     * @param {string} [options.rootPassword]
-     * @param {string} [options.authorizedKeys]
+     * the `%pre` variable-assignment block, and the `scripts/rocky-kickstart.sh` body.
+     * @param {object} options - Kickstart generation options.
+     * @param {string} [options.lang='en_US.UTF-8'] - System language for the ephemeral runtime.
+     * @param {string} [options.keyboard='us'] - Keyboard layout for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.timezone='America/New_York'] - Timezone for the ephemeral runtime AND the deployed OS.
+     * @param {string} [options.chronyConfPath='/etc/chrony.conf'] - chrony config path written in the deployed OS.
+     * @param {string} [options.rootPassword=process.env.MAAS_ADMIN_PASS] - root console password.
+     * @param {string} [options.adminUsername=''] - Primary (MAAS) admin user created in the deployed OS.
+     * @param {string} [options.adminPassword=''] - Primary admin console password (defaults to rootPassword).
+     * @param {string} [options.deployUsername=''] - Optional second (deploy) admin user (e.g. admin).
+     * @param {string} [options.deployPassword=''] - Deploy user console password (defaults to rootPassword).
+     * @param {string} [options.netIp=''] - Static IPv4 for the deployed OS; empty = DHCP.
+     * @param {number} [options.netPrefix=24] - IPv4 prefix length for the static address.
+     * @param {string} [options.netGateway=''] - Default gateway for the deployed OS.
+     * @param {string} [options.netDns=''] - DNS server for the deployed OS.
+     * @param {string} [options.authorizedKeys=''] - SSH public key(s) installed as authorized_keys.
+     * @param {string} [options.bootstrapUrl=''] - Base URL of the bootstrap HTTP server (status POSTs).
+     * @param {string} [options.workflowId=''] - Workflow identifier reported in status metadata.
+     * @param {string} [options.systemId=''] - MAAS system id reported in status metadata (if known).
+     * @param {string} [options.targetHostname=''] - Hostname reported in status metadata and set on the deployed OS.
+     * @param {number} [options.sshPort=22] - SSH port the ephemeral runtime listens on.
+     * @param {string} [options.installDiskHint=''] - Optional explicit target disk; empty = auto-detect.
+     * @param {boolean} [options.autoInstall=true] - When true, the runtime self-installs after a fallback timeout.
      * @memberof UnderpostKickStart
-     * @returns {string}
+     * @returns {string} The full kickstart (ks.cfg) source.
      */
     kickstartFactory: ({
       lang = 'en_US.UTF-8',
       keyboard = 'us',
       timezone = 'America/New_York',
+      chronyConfPath = '/etc/chrony.conf',
       rootPassword = process.env.MAAS_ADMIN_PASS,
+      adminUsername = '',
+      adminPassword = '',
+      deployUsername = '',
+      deployPassword = '',
+      netIp = '',
+      netPrefix = 24,
+      netGateway = '',
+      netDns = '',
       authorizedKeys = '',
+      bootstrapUrl = '',
+      workflowId = '',
+      systemId = '',
+      targetHostname = '',
+      sshPort = 22,
+      installDiskHint = '',
+      autoInstall = true,
     }) => {
-      const adminUsername = process.env.MAAS_ADMIN_USERNAME || 'maas';
+      const resolvedAdminUsername = adminUsername || process.env.MAAS_ADMIN_USERNAME || 'maas';
       const header = UnderpostKickStart.API.kickstartHeader({ lang, keyboard, timezone, rootPassword });
-      const variables = UnderpostKickStart.API.kickstartPreVariables({ rootPassword, authorizedKeys, adminUsername });
+      const variables = UnderpostKickStart.API.kickstartPreVariables({
+        rootPassword,
+        authorizedKeys,
+        adminUsername: resolvedAdminUsername,
+        adminPassword,
+        deployUsername,
+        deployPassword,
+        netIp,
+        netPrefix,
+        netGateway,
+        netDns,
+        timezone,
+        keyboardLayout: keyboard,
+        chronyConfPath,
+        bootstrapUrl,
+        workflowId,
+        systemId,
+        targetHostname,
+        sshPort,
+        installDiskHint,
+        autoInstall,
+      });
 
       const scriptPath = path.resolve(__dirname, '../../scripts/rocky-kickstart.sh');
       const scriptBody = fs.readFileSync(scriptPath, 'utf8');

package/src/cli/repository.js

@@ -22,7 +22,7 @@ import {
   buildReplicaId,
   writeEnv,
 } from '../server/conf.js';
-import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../server/client-build.js';
+import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../client-builder/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
@@ -106,6 +106,9 @@ class UnderpostRepository {
      * @param {boolean} [options.changelogBuild=false] - If true, scrapes all git history and builds a full CHANGELOG.md. Commits containing 'New release v:' are used as version section titles. Only commits starting with '[<tag>]' are included as entries.
      * @param {string} [options.changelogMinVersion=''] - If set, overrides the default minimum version limit (2.85.0) for --changelog-build.
      * @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`).
      * @memberof UnderpostRepository
      */
     commit(
@@ -135,6 +138,9 @@ class UnderpostRepository {
         bc: '',
         isRemoteRepo: '',
         hasChanges: false,
+        remoteUrl: false,
+        switchRepo: '',
+        targetBranch: '',
       },
     ) {
       if (!repoPath) repoPath = '.';
@@ -155,6 +161,22 @@ class UnderpostRepository {
         return;
       }
 
+      if (options.remoteUrl) {
+        const url = Underpost.repo.getRemoteUrl({ path: repoPath });
+        if (options.copy) pbcopy(url);
+        else console.log(url);
+        return;
+      }
+
+      if (options.switchRepo) {
+        Underpost.repo.switchRemote({
+          path: repoPath,
+          url: options.switchRepo,
+          branch: options.targetBranch || 'master',
+        });
+        return;
+      }
+
       if (options.bc) {
         console.log(
           shellExec(`cd ${repoPath} && git for-each-ref --contains ${options.bc} --format='%(refname:short)'`, {
@@ -1332,6 +1354,65 @@ Prevent build private config repo.`,
       return typeof raw === 'string' && /^[0-9a-f]{40}\t/m.test(raw);
     },
 
+    /**
+     * Returns the current URL of a git remote in plain text.
+     * @param {object} [opts]
+     * @param {string} [opts.path='.'] - Path to the git repository.
+     * @param {string} [opts.remote='origin'] - Remote name to query.
+     * @returns {string} The remote URL, or '' when the remote is not configured.
+     * @memberof UnderpostRepository
+     */
+    getRemoteUrl({ path: repoPath = '.', remote = 'origin' } = {}) {
+      return shellExec(`cd "${repoPath}" && git remote get-url ${remote}`, {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      }).trim();
+    },
+
+    /**
+     * Switches a local repository onto a different remote and force-syncs its
+     * working tree to a target branch, discarding local commits and tracked
+     * changes — effectively "switch repo to <url>#<branch>".
+     *
+     * Sequence (idempotent, re-runnable):
+     *   1. Normalize the URL (`owner/repo` → full GitHub HTTPS) and set/add the
+     *      remote, storing the token-free URL so no secret leaks into `.git/config`.
+     *   2. Force-fetch the target branch (auth injected inline for private repos).
+     *   3. Reset the working tree to the fetched tip and check out the target
+     *      branch, overwriting any current tracked content.
+     *
+     * Untracked files are intentionally left in place (no `git clean`).
+     *
+     * @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.remote='origin'] - Remote name to set and fetch from.
+     * @returns {void}
+     * @memberof UnderpostRepository
+     */
+    switchRemote({ url, path: repoPath = '.', branch = 'master', 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}`);
+      // 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@')) {
+        normalized = `https://github.com/${url}`;
+      }
+      const authUrl = Underpost.repo.resolveAuthUrl(url);
+      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}`);
+      // 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`);
+    },
+
     /**
      * Returns metadata about unpushed commits in a git repository.
      * Fetches from origin, then counts commits ahead of the remote branch.
@@ -1483,18 +1564,63 @@ Prevent build private config repo.`,
     },
 
     /**
-     * Runtime-type → in-pod site-root directory resolver.
-     * Maps each known runtime to the filesystem path where its repository lives inside the container.
-     * @param {string} runtime - The runtime identifier (e.g. 'wp').
-     * @param {string} host - The virtual-host name.
-     * @returns {string|null} Absolute path inside the pod, or null if the runtime has no known mapping.
+     * Resolves the in-pod site-root directory where a conf route's repository lives.
+     *
+     * General-purpose resolution, independent of any single runtime:
+     *   1. An explicit `directory` (the conf-declared document root) always wins.
+     *   2. Otherwise the runtime's base directory is used (e.g. `wp` → `/opt/lampp/htdocs/wp/<host>`).
+     *   3. A subdirectory route (e.g. `/wp`) appends `<subDir>` to the resolved root.
+     *
+     * This mirrors {@link WpService.createApp}'s `vhostDir`/`wpDir` layout so backups target the
+     * exact directory provisioning created, including subdirectory installs and custom directories.
+     *
+     * @param {object} opts
+     * @param {string} opts.runtime - The runtime identifier (e.g. 'wp').
+     * @param {string} opts.host - The virtual-host name.
+     * @param {string} [opts.routePath='/'] - The conf route path the repository is mounted under.
+     * @param {string} [opts.directory] - Explicit document root from conf; overrides the runtime base.
+     * @returns {string|null} Absolute path inside the pod, or null when neither a directory nor a
+     *   known runtime base resolves.
      * @memberof UnderpostRepository
      */
-    runtimeSiteRoot(runtime, host) {
-      const runtimePaths = {
+    runtimeSiteRoot({ runtime, host, routePath = '/', directory } = {}) {
+      const runtimeBase = {
         wp: `/opt/lampp/htdocs/wp/${host}`,
       };
-      return runtimePaths[runtime] || null;
+      const vhostDir = directory || runtimeBase[runtime];
+      if (!vhostDir) return null;
+      const subDir = routePath && routePath !== '/' ? routePath.replace(/^\/+/, '').replace(/\/+$/, '') : '';
+      return subDir ? `${vhostDir}/${subDir}` : vhostDir;
+    },
+
+    /**
+     * Probes a running pod for the first candidate directory that is a git repository
+     * (i.e. contains a `.git` entry). Used to locate a site root before backing it up so a
+     * missing/unprovisioned directory is detected up-front instead of producing an opaque
+     * shell `exit 1` from a failed `cd`.
+     *
+     * @param {object}   opts
+     * @param {string}   opts.podName   - Target pod name.
+     * @param {string}   opts.namespace - Kubernetes namespace.
+     * @param {string[]} opts.candidates - Absolute paths to probe, most-specific first.
+     * @returns {string|null} The first candidate that is a git repo, or null if none match.
+     * @memberof UnderpostRepository
+     */
+    podRepoDir({ podName, namespace, candidates }) {
+      const probe = candidates.map((dir) => `if [ -d '${dir}/.git' ]; then echo '${dir}'; exit 0; fi`).join('; ');
+      let out = '';
+      try {
+        out = Underpost.kubectl.exec({ podName, namespace, command: `${probe}; echo ''` }) || '';
+      } catch (err) {
+        logger.warn(`podRepoDir: probe failed in pod ${podName}`, err.message);
+        return null;
+      }
+      return (
+        out
+          .split('\n')
+          .map((line) => line.trim())
+          .find(Boolean) || null
+      );
     },
 
     /**
@@ -1543,12 +1669,28 @@ Prevent build private config repo.`,
           const entry = confServer[host][routePath];
           if (!entry.repository) continue;
 
-          const siteRoot = Underpost.repo.runtimeSiteRoot(entry.runtime, host);
-          if (!siteRoot) {
+          const siteRootArgs = { runtime: entry.runtime, host, directory: entry.directory };
+          const repoRoot = Underpost.repo.runtimeSiteRoot({ ...siteRootArgs, routePath });
+          if (!repoRoot) {
             logger.warn(`backupPodRepositories: no site-root mapping for runtime '${entry.runtime}' (${host})`);
             continue;
           }
 
+          // Probe the pod for the actual git repo so an unprovisioned/missing site root is
+          // detected and skipped cleanly instead of failing the in-pod `cd` with exit 1.
+          // Fall back to the vhost dir (root route) to cover conf/path drift.
+          const vhostRoot = Underpost.repo.runtimeSiteRoot({ ...siteRootArgs, routePath: '/' });
+          const candidates = [...new Set([repoRoot, vhostRoot].filter(Boolean))];
+          const siteRoot = Underpost.repo.podRepoDir({ podName, namespace, candidates });
+          if (!siteRoot) {
+            logger.warn(
+              `backupPodRepositories: no git repository found in pod ${podName} for ${host} (checked ${candidates.join(
+                ', ',
+              )}) — site may not be provisioned yet; skipping`,
+            );
+            continue;
+          }
+
           const repoName = entry.repository.split('/').pop().split('.')[0];
 
           // Build the backup script — secrets are injected as env vars in the exec,