cyberia 3.2.12 → 3.2.70

package/src/cli/repository.js

@@ -8,6 +8,7 @@ import dotenv from 'dotenv';
 import { commitData } from '../client/components/core/CommonJs.js';
 import { pbcopy, shellCd, shellExec } from '../server/process.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
+import path from 'path';
 import fs from 'fs-extra';
 import {
   getNpmRootPath,
@@ -21,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';
 
@@ -105,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(
@@ -133,16 +137,46 @@ class UnderpostRepository {
         p: undefined,
         bc: '',
         isRemoteRepo: '',
+        hasChanges: false,
+        remoteUrl: false,
+        switchRepo: '',
+        targetBranch: '',
       },
     ) {
       if (!repoPath) repoPath = '.';
 
+      if (options.hasChanges) {
+        const status = shellExec(`cd ${repoPath} && git status --porcelain`, {
+          stdout: true,
+          silent: true,
+          disableLog: true,
+        }).trim();
+        process.stdout.write(status ? '1' : '');
+        return;
+      }
+
       if (options.isRemoteRepo) {
         const accessible = Underpost.repo.isRemoteRepo(options.isRemoteRepo);
         console.log(accessible);
         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)'`, {
@@ -184,7 +218,7 @@ class UnderpostRepository {
         return;
       }
 
-      if (options.changelog !== undefined || options.changelogBuild) {
+      if (options.changelog !== undefined || options.changelogBuild || options.changelogMsg !== undefined) {
         const releaseMatch = 'New release v:';
         // Helper: parse [<tag>] commits into grouped sections
         const buildSectionChangelog = (commits) => {
@@ -221,7 +255,8 @@ class UnderpostRepository {
             stdout: true,
             silent: true,
             disableLog: true,
-          });
+            silentOnError: true,
+          }).toString();
           return rawLog
             .split('\n')
             .map((line) => {
@@ -312,15 +347,18 @@ class UnderpostRepository {
           fs.writeFileSync(changelogPath, `# Changelog\n\n${changelog}`);
           logger.info('CHANGELOG.md built at', changelogPath);
         } else {
-          // --changelog [latest-n]: print changelog of last N commits (default: 1)
-          const hasExplicitCount =
-            options.changelog !== undefined && options.changelog !== true && !isNaN(parseInt(options.changelog));
-          const scanLimit = hasExplicitCount ? parseInt(options.changelog) : 1;
-          const allCommits = fetchHistory(scanLimit);
-
-          const sections = buildVersionSections(allCommits);
-          let changelog = renderSections(sections);
-          console.log(changelog || `No changelog entries found.\n`);
+          // --changelog / --changelog-msg: message from the last N commits, where N is --from-n-commit
+          // (default 1, last commit only). No auto-detection.
+          const n = parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+          const sections = buildVersionSections(fetchHistory(n));
+          const changelog = renderSections(sections);
+          if (options.changelogMsg !== undefined) {
+            // Sanitized, commit-ready message; empty string when there are no tagged entries so
+            // callers fall back to their own generic default instead of a placeholder.
+            console.log(Underpost.repo.sanitizeChangelogMessage(changelog));
+          } else {
+            console.log(changelog || `No changelog entries found.\n`);
+          }
         }
 
         return;
@@ -556,7 +594,7 @@ class UnderpostRepository {
             // Handle sync-conf operation
             if (options.syncConf) {
               logger.info(`Syncing configuration for deploy ID: ${deployId}`);
-              shellExec(`node bin/build ${deployId} conf`);
+              shellExec(`node bin/build ${deployId} --conf`);
               logger.info('Configuration synced successfully');
               return resolve(true);
             }
@@ -608,7 +646,8 @@ class UnderpostRepository {
             const npmRoot = getNpmRootPath();
             const underpostRoot = options?.dev === true ? '.' : `${npmRoot}/underpost`;
             const destFolder = `./${projectName}`;
-            logger.info('build app', { destFolder });
+            const deployId = projectName.startsWith('dd-') ? projectName : `dd-${projectName}`;
+            logger.info('build app', { destFolder, deployId });
             if (fs.existsSync(destFolder)) fs.removeSync(destFolder);
             fs.mkdirSync(destFolder, { recursive: true });
             if (!options.dev) {
@@ -621,8 +660,9 @@ class UnderpostRepository {
               UnderpostRepository.API.initLocalRepo({ path: destFolder });
               shellExec(`cd ${destFolder} && git add . && git commit -m "Base template implementation"`);
             }
-            shellExec(`cd ${destFolder} && npm run build`);
-            shellExec(`cd ${destFolder} && npm run dev`);
+            shellExec(`cd ${destFolder} && node bin new --deploy-id ${deployId} --default-conf`);
+            shellExec(`cd ${destFolder} && node bin client ${deployId}`);
+            shellExec(`cd ${destFolder} && DEPLOY_ID=${deployId} npm run dev`);
           }
           return resolve(true);
         } catch (error) {
@@ -852,6 +892,7 @@ class UnderpostRepository {
               }
             }
             await buildClient({
+              deployId: resolvedDeployId,
               buildZip: options.buildZip || false,
               split: options.split || '',
               fullBuild: options.liteBuild ? false : true,
@@ -862,7 +903,12 @@ class UnderpostRepository {
                 logger.warn('Skip replica client build: replica folder not found', { replicaDeployId });
                 continue;
               }
-              await Underpost.repo.client(replicaDeployId);
+              await Underpost.repo.client(replicaDeployId, '', '', '', {
+                buildZip: options.buildZip || false,
+                split: options.split || '',
+                liteBuild: options.liteBuild || false,
+                iconsBuild: options.iconsBuild || false,
+              });
             }
 
             return resolve(true);
@@ -937,7 +983,7 @@ Prevent build private config repo.`,
           deployVersion: packageJsonDeploy.version,
         };
       }
-      shellExec(`node bin/build ${deployId} conf`);
+      shellExec(`node bin/build ${deployId} --conf`);
       return {
         validVersion: true,
         engineVersion: packageJsonEngine.version,
@@ -1215,17 +1261,40 @@ Prevent build private config repo.`,
       return copiedFiles;
     },
 
+    /**
+     * Resolves the default branch for a remote GitHub repository by querying
+     * `git ls-remote --symref` and extracting the HEAD ref target.
+     * Falls back to `main` when detection fails.
+     * @param {string} repo - The GitHub repository (e.g., "owner/repo").
+     * @returns {string} The default branch name (e.g. "main" or "master").
+     * @memberof UnderpostRepository
+     */
+    getDefaultBranch(repo) {
+      if (!repo) return 'main';
+      const authUrl = Underpost.repo.resolveAuthUrl(repo);
+      const raw = shellExec(
+        `GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote --symref "${authUrl}" HEAD 2>&1`,
+        { stdout: true, silent: true, disableLog: true, silentOnError: true },
+      );
+      // --symref emits a line like: ref: refs/heads/main	HEAD
+      const match = typeof raw === 'string' ? raw.match(/^ref:\s*refs\/heads\/(\S+)\tHEAD$/m) : null;
+      const branch = match ? match[1] : 'main';
+      logger.info('getDefaultBranch', { repo, branch });
+      return branch;
+    },
+
     /**
      * Dispatches a GitHub Actions workflow using gh CLI or curl fallback.
      * @param {object} options - Dispatch options.
      * @param {string} options.repo - The GitHub repository (e.g., "owner/repo").
      * @param {string} options.workflowFile - The workflow file name (e.g., "engine-core.cd.yml").
-     * @param {string} [options.ref='master'] - The git ref to dispatch against.
+     * @param {string} [options.ref] - The git ref to dispatch against. Auto-detects the remote's default branch when omitted.
      * @param {object} [options.inputs={}] - Key-value inputs for the workflow_dispatch event.
      * @memberof UnderpostRepository
      */
-    dispatchWorkflow(options = { repo: '', workflowFile: '', ref: 'master', inputs: {} }) {
-      const { repo, workflowFile, ref, inputs } = options;
+    dispatchWorkflow(options = { repo: '', workflowFile: '', ref: '', inputs: {} }) {
+      const { repo, workflowFile, inputs } = options;
+      const ref = options.ref || Underpost.repo.getDefaultBranch(repo);
       const ghAvailable = shellExec('command -v gh 2>/dev/null', {
         stdout: true,
         silent: true,
@@ -1302,14 +1371,77 @@ Prevent build private config repo.`,
       if (!url) return false;
       const authUrl = Underpost.repo.resolveAuthUrl(url);
       // GIT_TERMINAL_PROMPT=0 prevents git from hanging on credential prompts inside containers.
-      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git ls-remote "${authUrl}" HEAD 2>&1`, {
+      // `-c credential.helper=` disables any host-configured credential helper so its stderr
+      // warnings don't pollute the ls-remote output; the token is already embedded in authUrl.
+      const raw = shellExec(`GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote "${authUrl}" HEAD 2>&1`, {
         stdout: true,
         silent: true,
         disableLog: true,
         silentOnError: true,
       });
-      logger.info('isRemoteRepo', { url, raw: (raw || '').slice(0, 120) });
-      return typeof raw === 'string' && /^[0-9a-f]{40}\t/m.test(raw);
+      const refLine = typeof raw === 'string' ? (raw.match(/^[0-9a-f]{40}\t.*$/m) || [])[0] : undefined;
+      const accessible = !!refLine;
+      logger.info('isRemoteRepo', { url, accessible, ref: refLine || (raw || '').trim().split('\n').pop() });
+      return accessible;
+    },
+
+    /**
+     * 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`);
     },
 
     /**
@@ -1321,17 +1453,31 @@ Prevent build private config repo.`,
      * @memberof UnderpostRepository
      */
     getUnpushedCount(repoPath = '.', fallback = 1) {
+      // Every git call is silentOnError: a detached HEAD (CI checkout) or a missing upstream must
+      // degrade to the fallback, never throw — otherwise the thrown error is logged to stdout and
+      // can be captured as a commit message by callers that read this command's output.
       const branch = shellExec(`cd ${repoPath} && git branch --show-current`, {
         stdout: true,
         silent: true,
         disableLog: true,
-      }).trim();
-      shellExec(`cd ${repoPath} && git fetch origin 2>/dev/null`, { silent: true, disableLog: true });
+        silentOnError: true,
+      })
+        .toString()
+        .trim();
+      if (!branch) return { count: fallback, branch: '', hasUnpushed: false };
+      shellExec(`cd ${repoPath} && git fetch origin 2>/dev/null`, {
+        silent: true,
+        disableLog: true,
+        silentOnError: true,
+      });
       const raw = shellExec(`cd ${repoPath} && git rev-list --count origin/${branch}..HEAD 2>/dev/null`, {
         stdout: true,
         silent: true,
         disableLog: true,
-      }).trim();
+        silentOnError: true,
+      })
+        .toString()
+        .trim();
       const count = parseInt(raw);
       const hasUnpushed = !isNaN(count) && count > 0;
       return { count: hasUnpushed ? count : fallback, branch, hasUnpushed };
@@ -1346,7 +1492,7 @@ Prevent build private config repo.`,
      */
     sanitizeChangelogMessage(message) {
       if (!message) return '';
-      return message
+      const sanitized = message
         .replace(/^##\s+\d{4}-\d{2}-\d{2}\s*/gm, '')
         .replace(/^###\s+(\S+)\s*/gm, '[$1] ')
         .replace(/^- /gm, '')
@@ -1358,6 +1504,9 @@ Prevent build private config repo.`,
         .join('\n')
         .trim()
         .replaceAll('] - ', '] ');
+      // The empty-changelog placeholder must never become a commit message; return empty so
+      // callers fall back to their own generic default.
+      return sanitized === 'No changelog entries found.' ? '' : sanitized;
     },
     /**
      * Initializes a git repository at the given path and configures user identity
@@ -1374,8 +1523,9 @@ Prevent build private config repo.`,
       const gitEmail = process.env.GITHUB_EMAIL || `development@underpost.net`;
 
       if (!fs.existsSync(`${repoPath}/.git`)) {
-        shellExec(`cd "${repoPath}" && git init`);
+        shellExec(`mkdir -p "${repoPath}" && git init "${repoPath}"`);
       }
+
       shellExec(`cd "${repoPath}" && git config user.name '${gitUsername}'`);
       shellExec(`cd "${repoPath}" && git config user.email '${gitEmail}'`);
       shellExec(`cd "${repoPath}" && git config core.filemode false`);
@@ -1462,18 +1612,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
+      );
     },
 
     /**
@@ -1522,12 +1717,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,
@@ -1620,12 +1831,17 @@ Prevent build private config repo.`,
      *  4. Falls back to `${GITHUB_USERNAME}/engine` when no match is found.
      *
      * @param {string} [runtime=''] - The runtime identifier to look up (e.g. `'cyberia-server'`, `'cyberia-client'`).
+     * @param {boolean} [ownRuntimeRepo=false] - Whether to check for the runtime's own repository.
      * @returns {string} The resolved `owner/repo` string.
      * @memberof UnderpostRepository
      */
-    resolveInstanceRepo(runtime = '') {
+    resolveInstanceRepo(runtime = '', ownRuntimeRepo = false) {
       const fallback = `${process.env.GITHUB_USERNAME}/engine`;
       if (!runtime) return fallback;
+      // A `.dev` suffix selects the development image workflow
+      // (docker-image.<runtime>.dev.ci.yml) but resolves to the same instance
+      // repo as its production counterpart, so strip it before matching.
+      runtime = runtime.replace(/\.dev$/, '');
       const ddRouter = './engine-private/deploy/dd.router';
       const deployIds = fs.existsSync(ddRouter)
         ? fs
@@ -1651,8 +1867,91 @@ Prevent build private config repo.`,
           logger.warn(`[resolveInstanceRepo] failed to parse ${confPath}: ${err.message}`);
         }
       }
+      if (ownRuntimeRepo) {
+        const runtimeRepo = Underpost.repo.isRemoteRepo(`${process.env.GITHUB_USERNAME}/${runtime}`);
+        if (runtimeRepo) {
+          logger.info(`[resolveInstanceRepo] resolved from ${process.env.GITHUB_USERNAME}/${runtime}`, {
+            runtime,
+            repo: `${process.env.GITHUB_USERNAME}/${runtime}`,
+          });
+          return `${process.env.GITHUB_USERNAME}/${runtime}`;
+        }
+      }
       return fallback;
     },
+
+    /**
+     * Performs a shallow sparse Git checkout of a single subdirectory from any
+     * GitHub repository into a local target directory.
+     *
+     * Uses `--depth 1 --no-checkout` + `git sparse-checkout` so only the
+     * requested path is fetched — no full clone of the remote repo.
+     * Skips the clone entirely when `<targetDir>/<subPath>` already exists on
+     * disk (idempotent).
+     *
+     * Requires `GITHUB_TOKEN` to be set in the environment for authenticated
+     * access to private repositories.
+     *
+     * @param {string} subPath - The subdirectory path within the remote repo to
+     *   check out (e.g. `'conf/dd-prototype'`, `'src/api/payments'`).
+     * @param {object} [options]
+     * @param {string} [options.repoOwner='underpostnet'] - GitHub organisation or
+     *   user that owns the repository.
+     * @param {string} [options.repoName='engine-private'] - Name of the
+     *   repository on GitHub.
+     * @param {string} [options.targetDir='./engine-private'] - Local directory
+     *   where the repo will be cloned.
+     * @returns {boolean} `true` when the checkout was performed, `false` when it
+     *   was skipped because the target path already existed.
+     * @memberof UnderpostRepository
+     */
+    sparseCheckoutDirectory(
+      subPath,
+      options = { repoOwner: 'underpostnet', repoName: 'engine-private', targetDir: './engine-private' },
+    ) {
+      const { repoOwner = 'underpostnet', repoName = 'engine-private', targetDir = './engine-private' } = options;
+      const localPath = `${targetDir}/${subPath}`;
+      if (fs.existsSync(localPath)) {
+        logger.info('[sparseCheckoutDirectory] path already present, skipping', localPath);
+        return false;
+      }
+      const authUrl = `https://${process.env.GITHUB_TOKEN}@github.com/${repoOwner}/${repoName}.git`;
+      shellExec(`git clone --depth 1 --no-checkout ${authUrl} ${targetDir}`, { disableLog: true });
+      shellExec(`cd ${targetDir} && git sparse-checkout set ${subPath} && git checkout`, { disableLog: true });
+      logger.info('[sparseCheckoutDirectory] sparse checkout complete', localPath);
+      return true;
+    },
+
+    /**
+     * Ensures a deploy's public source repo (e.g. `engine-prototype`) is present
+     * next to the engine and reset to a pristine HEAD, so catalog `sourceMoves`
+     * can (re)pull custom sources even after a previous build moved them out of
+     * the source tree.
+     *
+     * Clones `../<repoName>` when missing; otherwise restores a clean checkout
+     * (`git checkout .` brings back any moved-out tracked files) and pulls latest.
+     * Mirrors the sibling-repo handling used by `syncPrivateConf`.
+     *
+     * @param {string} repoName - Public source repo name (e.g. `engine-prototype`).
+     * @returns {boolean} `true` when the repo is available on disk.
+     * @memberof UnderpostRepository
+     */
+    pullSourceRepo(repoName) {
+      const username = process.env.GITHUB_USERNAME;
+      if (!username || !repoName) return false;
+      const repoPath = `../${repoName}`;
+      const gitUri = `${username}/${repoName}`;
+      if (!fs.existsSync(repoPath)) {
+        shellExec(`cd .. && underpost clone ${gitUri}`, { silent: true });
+      } else {
+        const repoAbsPath = path.resolve(repoPath);
+        shellExec(`git config --global --add safe.directory '${repoAbsPath}'`);
+        shellExec(`cd ${repoPath} && git checkout . && git clean -f -d && underpost pull . ${gitUri}`, {
+          silent: true,
+        });
+      }
+      return fs.existsSync(repoPath);
+    },
   };
 }