underpost 3.2.11 → 3.2.14

package/src/cli/repository.js

@@ -556,7 +556,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);
             }
@@ -852,6 +852,7 @@ class UnderpostRepository {
               }
             }
             await buildClient({
+              deployId: resolvedDeployId,
               buildZip: options.buildZip || false,
               split: options.split || '',
               fullBuild: options.liteBuild ? false : true,
@@ -862,7 +863,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 +943,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,
@@ -1653,6 +1659,77 @@ Prevent build private config repo.`,
       }
       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 {
+        shellExec(`cd ${repoPath} && git checkout . && git clean -f -d && underpost pull . ${gitUri}`, {
+          silent: true,
+        });
+      }
+      return fs.existsSync(repoPath);
+    },
   };
 }
 

package/src/cli/run.js

@@ -15,6 +15,7 @@ import {
   getNpmRootPath,
   isDeployRunnerContext,
   loadConfServerJson,
+  loadReplicas,
   writeEnv,
 } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
@@ -422,6 +423,7 @@ class UnderpostRun {
         return;
       }
       shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
 
       // Capture last N commit messages for propagation.
       // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
@@ -502,6 +504,7 @@ class UnderpostRun {
         return;
       }
       shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
 
       // Capture last N commit messages from the engine repo.
       // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
@@ -713,6 +716,11 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       let targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'green';
       if (targetTraffic) versions = versions ? versions : targetTraffic;
 
+      const ignorePods =
+        isDeployRunnerContext(path, options) && targetTraffic
+          ? Underpost.kubectl.get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace).map((p) => p.NAME)
+          : [];
+
       const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
       const cmdString = options.cmd
         ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
@@ -743,7 +751,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
-        await Underpost.deploy.monitorReadyRunner(deployId, env, targetTraffic, [], options.namespace, 'underpost');
+        await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
         Underpost.deploy.switchTraffic(deployId, env, targetTraffic, replicas, options.namespace, options);
       } else
         logger.info('current traffic', Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }));
@@ -1154,7 +1162,7 @@ EOF
 `,
           { disableLog: true },
         );
-        const { ready, readyPods } = await Underpost.deploy.monitorReadyRunner(
+        const { ready, readyPods } = await Underpost.monitor.monitorReadyRunner(
           _deployId,
           env,
           targetTraffic,
@@ -1436,8 +1444,8 @@ EOF`);
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const currentImage = options.imageName
         ? options.imageName
-        : Underpost.deploy
-            .getCurrentLoadedImages(options.nodeName ? options.nodeName : 'kind-worker', false)
+        : Underpost.image
+            .getCurrentLoaded(options.nodeName ? options.nodeName : 'kind-worker', false)
             .find((o) => o.IMAGE.match('underpost'));
       const podName = options.podName || `underpost-dev-container`;
       const volumeHostPath = options.claimName || '/home/dd';
@@ -1714,20 +1722,13 @@ EOF`);
       const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
       const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
       const env = options.dev ? 'development' : 'production';
-      const ignorePods = Underpost.deploy
+      const ignorePods = Underpost.kubectl
         .get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace)
         .map((p) => p.NAME);
 
       shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic} -n ${options.namespace}`);
 
-      await Underpost.deploy.monitorReadyRunner(
-        deployId,
-        env,
-        targetTraffic,
-        ignorePods,
-        options.namespace,
-        'underpost',
-      );
+      await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
 
       Underpost.deploy.switchTraffic(deployId, env, targetTraffic, options.replicas, options.namespace, options);
     },
@@ -1819,7 +1820,7 @@ EOF`);
         }`;
         shellExec(cmd, { async: true });
       }
-      await awaitDeployMonitor(true);
+      if ((await awaitDeployMonitor()) !== true) return;
       {
         const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
 
@@ -1827,7 +1828,7 @@ EOF`);
           async: true,
         });
       }
-      await awaitDeployMonitor(true);
+      if ((await awaitDeployMonitor()) !== true) return;
       shellExec(
         `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
       );
@@ -2504,7 +2505,8 @@ EOF`;
     /**
      * @method push-bundle
      * @description Builds the client zip for the specified deployment, splits it into parts, and uploads to file storage.
-     *   Steps: set env, build+split zip, switch to cron env, upload parts to storage.
+     *   Steps: set env, build+split zip, upload only the zip parts belonging to the deploy-id's hosts (from conf.server.json).
+     *   Only files matching `<host>-<route>.zip.part*` or `<host>-<route>.zip` for each non-skipped route are uploaded.
      * @param {string} path - Optional `fsPath.splitOption` string.
      *   Examples: `build` (default split 8), `build.16` (split 16 MB), `build.none-split` (no split flag).
      * @param {Object} options - The default underpost runner options for customizing workflow.
@@ -2513,7 +2515,7 @@ EOF`;
      * @memberof UnderpostRun
      */
     'push-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
       const env = options.dev ? 'development' : 'production';
       const deployId = options.deployId || 'dd-default';
       const pathParts = (path || '').split('.');
@@ -2537,11 +2539,54 @@ EOF`;
         }
       }
 
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
+      const storageFilePath = `engine-private/conf/${deployId}/storage.bundle.json`;
+
       shellExec(`${baseCommand} env ${deployId} ${env}`);
       shellExec(`${baseCommand} client ${deployId} --build-zip${splitFlag ? ` ${splitFlag}` : ''}`);
-      shellExec(
-        `${baseCommand} fs ${fsPath} --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --force`,
-      );
+
+      const pushBundleFiles = (host, routePath) => {
+        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+        const buildDir = `./${fsPath}`;
+        if (!fs.existsSync(buildDir)) return;
+        const partFiles = fs
+          .readdirSync(buildDir)
+          .filter(
+            (name) =>
+              name.startsWith(`${buildId}.zip.part`) ||
+              name.startsWith(`${buildId}.zip-part`) ||
+              name === `${buildId}.zip`,
+          )
+          .map((name) => `${fsPath}/${name}`);
+        if (partFiles.length === 0) {
+          logger.warn(`push-bundle: no bundle files found for '${host}${routePath}'`, { buildId });
+          return;
+        }
+        for (const partFile of partFiles) {
+          shellExec(
+            `${baseCommand} fs ${partFile} --deploy-id ${deployId} --storage-file-path ${storageFilePath} --force`,
+          );
+        }
+      };
+
+      for (const host of Object.keys(confServer)) {
+        for (const routePath of Object.keys(confServer[host])) {
+          const routeConf = confServer[host][routePath] || {};
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pushBundleFiles(host, replica);
+              }
+            }
+            continue;
+          }
+          pushBundleFiles(host, routePath);
+        }
+      }
     },
 
     /**
@@ -2558,11 +2603,13 @@ EOF`;
      * @memberof UnderpostRun
      */
     'pull-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
       const env = options.dev ? 'development' : 'production';
       const deployId = options.deployId || 'dd-default';
       const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-      const confServer = fs.existsSync(confServerPath) ? loadConfServerJson(confServerPath) : {};
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
       const hostsArg = path
         ? path
             .split(',')
@@ -2581,60 +2628,59 @@ EOF`;
         `${baseCommand} fs build --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --pull --omit-unzip`,
       );
 
+      const pullBundleRoute = (host, routePath) => {
+        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+        const zipPath = `build/${buildId}.zip`;
+        const buildDir = './build';
+        const hasZip = fs.existsSync(zipPath);
+        const hasParts =
+          fs.existsSync(buildDir) &&
+          fs
+            .readdirSync(buildDir)
+            .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
+
+        if (!hasZip && !hasParts) {
+          logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
+          return;
+        }
+
+        if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
+        shellExec(`${baseCommand} client --unzip ${zipPath}`);
+        shellExec(`sudo rm -rf ${zipPath}`);
+
+        if (fs.existsSync(buildDir)) {
+          fs.readdirSync(buildDir)
+            .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
+            .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
+        }
+
+        const extractedDir = `build/${buildId.replace(/-$/, '')}`;
+        if (!fs.existsSync(extractedDir)) {
+          logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+          return;
+        }
+
+        const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
+        if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
+        if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
+        fs.copySync(`${extractedDir}`, `${publicDestPath}`);
+      };
+
       for (const host of hostsArg) {
-        // Gather all routes for this host; fall back to root '/' when host is not in confServer
-        // (e.g. when hosts were provided explicitly via the path argument).
         const routePaths = confServer[host] ? Object.keys(confServer[host]) : ['/'];
 
         for (const routePath of routePaths) {
           const routeConf = confServer[host] ? confServer[host][routePath] || {} : {};
-          // Skip routes that are not built by buildClient (mirrors buildClient skip conditions)
-          if (routeConf.singleReplica || routeConf.redirect || routeConf.disabledRebuild) continue;
-
-          // buildClient names the zip as "<host>-<path-no-slashes>.zip"
-          // e.g. host="underpost.net", path="/" → buildId="underpost.net-", zip="build/underpost.net-.zip"
-          // e.g. host="app.net", path="/admin" → buildId="app.net-admin", zip="build/app.net-admin.zip"
-          const buildId = `${host}-${routePath.replaceAll('/', '')}`;
-          const zipPath = `build/${buildId}.zip`;
-          const buildDir = './build';
-          const hasZip = fs.existsSync(zipPath);
-          const hasParts =
-            fs.existsSync(buildDir) &&
-            fs
-              .readdirSync(buildDir)
-              .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
-
-          if (!hasZip && !hasParts) {
-            logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
-            continue;
-          }
-
-          if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
-          shellExec(`${baseCommand} client --unzip ${zipPath}`);
-          shellExec(`sudo rm -rf ${zipPath}`);
-
-          // Clean up downloaded part wrapper zips left by --omit-unzip pull
-          if (fs.existsSync(buildDir)) {
-            fs.readdirSync(buildDir)
-              .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
-              .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
-          }
-
-          // unzipClientBuild extracts to buildId with trailing '-' stripped
-          // e.g. "build/underpost.net-" → "build/underpost.net"
-          // e.g. "build/app.net-admin" → "build/app.net-admin" (no trailing dash, no change)
-          const extractedDir = `build/${buildId.replace(/-$/, '')}`;
-          if (!fs.existsSync(extractedDir)) {
-            logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pullBundleRoute(host, replica);
+              }
+            }
             continue;
           }
-
-          // Destination mirrors the public directory layout used by the server
-          const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
-          if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
-          // Ensure parent directory exists for sub-paths
-          if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
-          shellExec(`sudo mv ${extractedDir} ${publicDestPath}`);
+          pullBundleRoute(host, routePath);
         }
       }
     },

package/src/index.js

@@ -44,7 +44,7 @@ class Underpost {
    * @type {String}
    * @memberof Underpost
    */
-  static version = 'v3.2.11';
+  static version = 'v3.2.14';
 
   /**
    * Required Node.js major version

package/src/runtime/wp/Dockerfile

@@ -3,7 +3,7 @@ FROM rockylinux:9
 # System packages 
 RUN dnf -y update && \
     dnf -y install epel-release && \
-    dnf -y install --allowerasing \
+    dnf -y install --allowerasing --nobest \
     bzip2 \
     sudo \
     curl \
@@ -20,8 +20,8 @@ RUN dnf -y update && \
     perl && \
     dnf clean all
 
-# Download and install XAMPP (PHP 8.2)
-RUN curl -L -o /tmp/xampp-linux-installer.run "https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/8.2.12/xampp-linux-x64-8.2.12-0-installer.run" && \
+# Download and install XAMPP (PHP 8.2) with retry logic for flaky SourceForge transfers
+RUN curl -L --retry 5 --retry-delay 10 --retry-max-time 180 -o /tmp/xampp-linux-installer.run "https://sourceforge.net/projects/xampp/files/XAMPP%20Linux/8.2.12/xampp-linux-x64-8.2.12-0-installer.run" && \
     chmod +x /tmp/xampp-linux-installer.run && \
     bash -c "/tmp/xampp-linux-installer.run --mode unattended" && \
     ln -sf /opt/lampp/lampp /usr/bin/lampp

package/src/server/catalog-underpost.js

@@ -0,0 +1,61 @@
+/**
+ * Underpost platform content catalog — the base `pwa-microservices-template`.
+ *
+ * @module src/server/catalog-underpost.js
+ * @namespace UnderpostCatalog
+ */
+
+/**
+ * Workflow + service files re-added to the template after the engine-only strip.
+ * @constant {string[]}
+ * @memberof UnderpostCatalog
+ */
+const TEMPLATE_RESTORE_PATHS = [
+  `./src/server/catalog-underpost.js`,
+  `./.github/workflows/pwa-microservices-template-page.cd.yml`,
+  `./.github/workflows/pwa-microservices-template-test.ci.yml`,
+  `./.github/workflows/npmpkg.ci.yml`,
+  `./.github/workflows/ghpkg.ci.yml`,
+  `./.github/workflows/gitlab.ci.yml`,
+  `./.github/workflows/publish.ci.yml`,
+  `./.github/workflows/release.cd.yml`,
+  `./src/client/services/user/guest.service.js`,
+  './src/api/user/guest.service.js',
+  './src/ws/IoInterface.js',
+  './src/ws/IoServer.js',
+  './manifests/deployment/dd-default-development',
+];
+
+/**
+ * npm keywords for the standalone Underpost platform / template package.
+ * @constant {string[]}
+ * @memberof UnderpostCatalog
+ */
+const TEMPLATE_KEYWORDS = [
+  'underpost',
+  'underpost-platform',
+  'cli',
+  'toolchain',
+  'ci-cd',
+  'devops',
+  'kubernetes',
+  'k3s',
+  'kubeadm',
+  'lxd',
+  'baremetal',
+  'container-orchestration',
+  'image-management',
+  'pwa',
+  'workbox',
+  'microservices',
+];
+
+/**
+ * npm description for the standalone Underpost platform / template package.
+ * @constant {string}
+ * @memberof UnderpostCatalog
+ */
+const TEMPLATE_DESCRIPTION =
+  'Underpost Platform — end-to-end CI/CD and application-delivery toolchain CLI. Covers bare metal, Kubernetes, K3s, kubeadm, LXD, container/image orchestration, secrets, databases, cron jobs, monitoring, SSH, runners, PWA + Workbox delivery, and release orchestration. Extensible via downstream CLIs.';
+
+export { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION };

package/src/server/catalog.js

@@ -0,0 +1,77 @@
+/**
+ * Dynamic product-catalog resolver.
+ *
+ * Product catalogs (`catalog-<suffix>.js`, e.g. `catalog-cyberia`, `catalog-prototype`)
+ * are loaded lazily by deploy id via ES dynamic `import()` so the base build
+ * (`bin/build`) and template assembly (`bin/build.template`) never statically
+ * depend on any product module. Removing a product catalog simply makes its
+ * deploy id resolve to the empty catalog — nothing else breaks.
+ *
+ * Each product catalog default-exports the uniform shape documented in
+ * {@link module:src/server/catalog-cyberia}.
+ *
+ * @module src/server/catalog.js
+ * @namespace Catalog
+ */
+
+import fs from 'fs-extra';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+
+const catalogDir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Empty product catalog returned for deploy ids without a dedicated module. */
+const EMPTY_CATALOG = {
+  sourceMoves: [],
+  privateConfPaths: [],
+  templatePaths: [],
+  stripPaths: [],
+  keywords: [],
+  description: '',
+};
+
+/**
+ * Loads a single deploy id's product catalog. The suffix after `dd-` selects the
+ * module (`dd-cyberia` → `catalog-cyberia.js`). Returns {@link EMPTY_CATALOG} when
+ * the deploy id has no dedicated catalog or the module cannot be loaded.
+ *
+ * @method loadDeployCatalog
+ * @param {string} deployId - A concrete deploy id (e.g. `dd-cyberia`).
+ * @returns {Promise<object>} The product catalog (uniform shape).
+ * @memberof Catalog
+ */
+const loadDeployCatalog = async (deployId) => {
+  const suffix = (deployId ?? '').split('dd-')[1];
+  if (!suffix) return EMPTY_CATALOG;
+  try {
+    const mod = await import(`./catalog-${suffix}.js`);
+    return { ...EMPTY_CATALOG, ...(mod.default ?? {}) };
+  } catch {
+    return EMPTY_CATALOG;
+  }
+};
+
+/**
+ * Loads every product catalog present alongside this module (`catalog-*.js`,
+ * excluding the base `catalog-underpost` and this resolver). Used to aggregate
+ * product `stripPaths` for the base template without naming any product.
+ *
+ * @method loadProductCatalogs
+ * @returns {Promise<object[]>} Loaded product catalogs (uniform shape).
+ * @memberof Catalog
+ */
+const loadProductCatalogs = async () => {
+  const catalogs = [];
+  for (const file of fs.readdirSync(catalogDir)) {
+    if (!/^catalog-.+\.js$/.test(file) || file === 'catalog-underpost.js') continue;
+    try {
+      const mod = await import(`./${file}`);
+      if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
+    } catch {
+      /* a malformed/removed product catalog must not break the base build */
+    }
+  }
+  return catalogs;
+};
+
+export { loadDeployCatalog, loadProductCatalogs, EMPTY_CATALOG };