cyberia 3.2.9 → 3.2.22

package/src/server/conf.js

@@ -10,6 +10,7 @@ import dotenv from 'dotenv';
 import {
   capFirst,
   getCapVariableName,
+  getDirname,
   newInstance,
   orderAbc,
   orderArrayFromAttrInt,
@@ -41,6 +42,20 @@ const logger = loggerFactory(import.meta);
  */
 const ENV_REF_PREFIX = 'env:';
 
+/**
+ * Resolves a standardized context key from host/path descriptors.
+ * The key is used across DB, WS, mailer, and cache registries.
+ *
+ * @method resolveHostKeyContext
+ * @param {{host?: string, path?: string}|string} [context={ host: '', path: '' }] - Context object or prebuilt key.
+ * @returns {string} Host key context string.
+ * @memberof ServerConfBuilder
+ */
+const resolveHostKeyContext = (context = { host: '', path: '' }) => {
+  if (typeof context === 'string') return context;
+  return `${context.host || ''}${context.path || ''}`;
+};
+
 /**
  * Recursively walks a configuration object and replaces every string value that
  * starts with {@link ENV_REF_PREFIX} (`"env:"`) with the corresponding
@@ -320,25 +335,29 @@ const Config = {
 
     if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
 
-    const envTemplate = fs.existsSync('./.env.example')
+    const sharedEnvTemplate = fs.existsSync('./.env.example')
       ? fs.readFileSync('./.env.example', 'utf8')
       : fs.existsSync('./.env.production')
         ? fs.readFileSync('./.env.production', 'utf8')
         : '';
 
-    if (envTemplate) {
-      const prodEnv = envTemplate.replaceAll('dd-default', deployId);
-      fs.writeFileSync(`${folder}/.env.production`, prodEnv, 'utf8');
-      fs.writeFileSync(
-        `${folder}/.env.development`,
-        prodEnv.replace('NODE_ENV=production', 'NODE_ENV=development').replace('PORT=3000', 'PORT=4000'),
-        'utf8',
-      );
-      fs.writeFileSync(
-        `${folder}/.env.test`,
-        prodEnv.replace('NODE_ENV=production', 'NODE_ENV=test').replace('PORT=3000', 'PORT=5000'),
-        'utf8',
-      );
+    const envTemplates = {
+      production: fs.existsSync('./.env.production') ? fs.readFileSync('./.env.production', 'utf8') : sharedEnvTemplate,
+      development: fs.existsSync('./.env.development')
+        ? fs.readFileSync('./.env.development', 'utf8')
+        : sharedEnvTemplate
+          ? sharedEnvTemplate.replace('NODE_ENV=production', 'NODE_ENV=development').replace('PORT=3000', 'PORT=4000')
+          : '',
+      test: fs.existsSync('./.env.test')
+        ? fs.readFileSync('./.env.test', 'utf8')
+        : sharedEnvTemplate
+          ? sharedEnvTemplate.replace('NODE_ENV=production', 'NODE_ENV=test').replace('PORT=3000', 'PORT=5000')
+          : '',
+    };
+
+    for (const [envName, envTemplate] of Object.entries(envTemplates)) {
+      if (!envTemplate) continue;
+      fs.writeFileSync(`${folder}/.env.${envName}`, envTemplate.replaceAll('dd-default', deployId), 'utf8');
     }
 
     fs.writeFileSync(
@@ -1067,13 +1086,9 @@ const buildPortProxyRouter = (
 
   if (Object.keys(router).length === 0) return router;
 
-  if (options.devProxyContext === true && process.env.NODE_ENV === 'development') {
-    const confDevApiServer = JSON.parse(
-      fs.readFileSync(
-        `./engine-private/conf/${process.argv[3]}/conf.server.dev.${process.argv[4]}-dev-api.json`,
-        'utf8',
-      ),
-    );
+  const devApiConfPath = `./engine-private/conf/${process.argv[3]}/conf.server.dev.${process.argv[4]}-dev-api.json`;
+  if (options.devProxyContext === true && process.env.NODE_ENV === 'development' && fs.existsSync(devApiConfPath)) {
+    const confDevApiServer = JSON.parse(fs.readFileSync(devApiConfPath, 'utf8'));
     let devApiHosts = [];
     let origins = [];
     for (const _host of Object.keys(confDevApiServer))
@@ -1208,7 +1223,11 @@ const validateTemplatePath = (absolutePath = '') => {
   const confSsr = DefaultConf.ssr[ssr];
   const clients = DefaultConf.client.default.services;
 
-  if (absolutePath.match('src/api') && !confServer.apis.find((p) => absolutePath.match(`src/api/${p}/`))) {
+  if (
+    absolutePath.match('src/api') &&
+    !absolutePath.match('src/api/types.js') &&
+    !confServer.apis.find((p) => absolutePath.match(`src/api/${p}/`))
+  ) {
     return false;
   }
   if (absolutePath.match('conf.dd-') && absolutePath.match('.js')) return false;
@@ -1250,14 +1269,8 @@ const validateTemplatePath = (absolutePath = '') => {
     return false;
   }
   if (
-    absolutePath.match('src/client/ssr/offline') &&
-    !confSsr.offline.find((p) => absolutePath.match(`src/client/ssr/offline/${p.client}.js`))
-  ) {
-    return false;
-  }
-  if (
-    absolutePath.match('src/client/ssr/pages') &&
-    !confSsr.pages.find((p) => absolutePath.match(`src/client/ssr/pages/${p.client}.js`))
+    absolutePath.match('src/client/ssr/views') &&
+    !(confSsr.views || []).find((p) => absolutePath.match(`src/client/ssr/views/${p.client}.js`))
   ) {
     return false;
   }
@@ -1279,15 +1292,19 @@ const validateTemplatePath = (absolutePath = '') => {
 /**
  * @method awaitDeployMonitor
  * @description Waits for the deploy monitor.
- * @param {boolean} [init=false] - The init flag.
+ * @param {boolean} [isFinal=false] - If true, logs when the final (non-replica) deployment completes.
  * @param {number} [deltaMs=1000] - The delta ms.
- * @returns {Promise<void>} - The await deploy monitor.
+ * @param {boolean} [callback=false] - The callback.
+ * @returns {Promise<boolean>} - `false` if `container-status=error` was detected, `true` on clean completion.
  * @memberof ServerConfBuilder
  */
-const awaitDeployMonitor = async (init = false, deltaMs = 1000) => {
-  if (init) Underpost.env.set('await-deploy', new Date().toISOString());
+const awaitDeployMonitor = async (isFinal = false, deltaMs = 1000, callback = false) => {
+  if (!callback) Underpost.env.set('await-deploy', new Date().toISOString());
+  if (isFinal) logger.info('Final deployment running (no replica)');
   await timer(deltaMs);
-  if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor();
+  if (Underpost.env.get('container-status') === 'error') return false;
+  if (Underpost.env.get('await-deploy')) return await awaitDeployMonitor(false, deltaMs, true);
+  return true;
 };
 
 /**
@@ -1312,59 +1329,6 @@ const mergeFile = async (parts = [], outputFilePath) => {
   });
 };
 
-/**
- * @method rebuildConfFactory
- * @description Rebuilds the conf factory.
- * @param {object} options - The options.
- * @param {string} options.deployId - The deploy ID.
- * @param {string} options.valkey - The valkey.
- * @param {boolean} [options.mongo=false] - The mongo.
- * @returns {object} - The rebuild conf factory.
- * @memberof ServerConfBuilder
- */
-const rebuildConfFactory = ({ deployId, valkey, mongo }) => {
-  const confServer = loadReplicas(deployId, loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`));
-  const hosts = {};
-  for (const host of Object.keys(confServer)) {
-    hosts[host] = {};
-    for (const path of Object.keys(confServer[host])) {
-      if (!confServer[host][path].db) continue;
-      const { singleReplica, replicas, db } = confServer[host][path];
-      const { provider } = db;
-      if (singleReplica) {
-        for (const replica of replicas) {
-          const deployIdReplica = buildReplicaId({ replica, deployId });
-          const confServerReplica = loadConfServerJson(`./engine-private/replica/${deployIdReplica}/conf.server.json`);
-          for (const _host of Object.keys(confServerReplica)) {
-            for (const _path of Object.keys(confServerReplica[_host])) {
-              hosts[host][_path] = { replica: { host, path } };
-              confServerReplica[_host][_path].valkey = valkey;
-              switch (provider) {
-                case 'mongoose':
-                  confServerReplica[_host][_path].db.host = mongo.host;
-                  break;
-              }
-            }
-          }
-          fs.writeFileSync(
-            `./engine-private/replica/${deployIdReplica}/conf.server.json`,
-            JSON.stringify(confServerReplica, null, 4),
-            'utf8',
-          );
-        }
-      } else hosts[host][path] = {};
-      confServer[host][path].valkey = valkey;
-      switch (provider) {
-        case 'mongoose':
-          confServer[host][path].db.host = mongo.host;
-          break;
-      }
-    }
-  }
-  fs.writeFileSync(`./engine-private/conf/${deployId}/conf.server.json`, JSON.stringify(confServer, null, 4), 'utf8');
-  return { hosts };
-};
-
 /**
  * @method getPathsSSR
  * @description Gets the paths SSR.
@@ -1377,8 +1341,7 @@ const getPathsSSR = (conf) => {
   for (const o of conf.head) paths.push(`src/client/ssr/head/${o}.js`);
   for (const o of conf.body) paths.push(`src/client/ssr/body/${o}.js`);
   for (const o of Object.keys(conf.mailer)) paths.push(`src/client/ssr/mailer/${conf.mailer[o]}.js`);
-  for (const o of conf.offline) paths.push(`src/client/ssr/mailer/${o.client}.js`);
-  for (const o of conf.pages) paths.push(`src/client/ssr/pages/${o.client}.js`);
+  for (const o of conf.views || []) paths.push(`src/client/ssr/views/${o.client}.js`);
   return paths;
 };
 
@@ -1457,65 +1420,131 @@ const writeEnv = (envPath, envObj) =>
 
 /**
  * @method buildCliDoc
- * @description Builds the CLI documentation.
- * @param {object} program - The program.
- * @param {string} oldVersion - The old version.
- * @param {string} newVersion - The new version.
+ * @description Scrapes `node bin help` (and `node bin help <command>` for every
+ * registered command) and renders a structured Markdown reference: a command
+ * index with anchor links, plus a per-command section with its description,
+ * usage, and Arguments/Options rendered as tables. Writes
+ * `CLI-HELP.md` + the served reference doc, and refreshes the README CLI index.
+ * @param {object} program - The commander program.
+ * @param {string} oldVersion - The old version string to replace.
+ * @param {string} newVersion - The new version string.
  * @memberof ServerConfBuilder
  */
 const buildCliDoc = (program, oldVersion, newVersion) => {
-  let md = shellExec(`node bin help`, { silent: true, stdout: true }).split('Options:');
-  const baseOptions =
-    `## ${md[0].split(`\n`)[2]}
-
-### Usage: ` +
-    '`' +
-    md[0].split(`\n`)[0].split('Usage: ')[1] +
-    '`' +
-    `
-  ` +
-    '```\n Options:' +
-    md[1] +
-    ' \n```';
-  md =
-    baseOptions +
-    `
-
-## Commands:
-    `;
-  program.commands.map((o) => {
-    md +=
-      `
-
-` +
-      '### `' +
-      o._name +
-      '` :' +
-      `
-` +
-      '```\n ' +
-      shellExec(`node bin help ${o._name}`, { silent: true, stdout: true }) +
-      ' \n```' +
-      `
-  `;
-  });
-  md = md.replaceAll(oldVersion, newVersion);
+  const help = (args = '') => shellExec(`node bin help${args ? ` ${args}` : ''}`, { silent: true, stdout: true });
+  // Escape table-breaking pipes and collapse wrapped whitespace for a Markdown cell.
+  const cell = (s) => String(s).replace(/\s+/g, ' ').replaceAll('|', '\\|').trim();
+  const anchor = (name) => `underpost-${name}`.toLowerCase().replace(/[^a-z0-9-]/g, '');
+
+  // Parse a commander help block into { usage, description, sections: { Options, Arguments, Commands } }.
+  const parseHelp = (text) => {
+    const lines = text.split('\n');
+    const usageMatch = lines[0].match(/^Usage:\s*(.*)$/);
+    const usage = usageMatch ? usageMatch[1].trim() : '';
+    const sections = {};
+    const descLines = [];
+    let current = null;
+    let buf = [];
+    const flush = () => {
+      if (current) sections[current] = buf.join('\n');
+      buf = [];
+    };
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      const head = line.match(/^([A-Za-z][\w ]*):\s*$/); // top-level "Options:", "Arguments:", "Commands:"
+      if (head) {
+        flush();
+        current = head[1].trim();
+      } else if (current !== null) {
+        buf.push(line);
+      } else {
+        descLines.push(line);
+      }
+    }
+    flush();
+    return { usage, description: descLines.join('\n').trim(), sections };
+  };
+
+  // Parse a columnar "  <term>   <description>" section (descriptions may wrap onto
+  // indented continuation lines) into [{ term, desc }].
+  const parseEntries = (text = '') => {
+    const entries = [];
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      const leading = line.length - line.trimStart().length;
+      if (leading <= 2) {
+        const rest = line.trim();
+        const gap = rest.search(/\s{2,}/);
+        entries.push(gap === -1 ? { term: rest, desc: '' } : { term: rest.slice(0, gap), desc: rest.slice(gap) });
+      } else if (entries.length) {
+        entries[entries.length - 1].desc += ` ${line.trim()}`;
+      }
+    }
+    return entries;
+  };
+
+  const table = (head, entries) =>
+    !entries.length
+      ? ''
+      : `| ${head[0]} | ${head[1]} |\n| --- | --- |\n` +
+        entries.map(({ term, desc }) => `| \`${cell(term)}\` | ${cell(desc)} |`).join('\n') +
+        '\n';
+
+  const detailSection = (sections, name, head) => {
+    const t = table(head, parseEntries(sections[name]));
+    return t ? `\n#### ${name}\n\n${t}` : '';
+  };
+
+  // ── Top-level index ──
+  const root = parseHelp(help());
+  const commandEntries = parseEntries(root.sections['Commands']).filter((e) => e.term.split(' ')[0] !== 'help');
+
+  const index =
+    `## Underpost CLI\n\n` +
+    (root.description ? `> ${root.description.replace(/\s+/g, ' ')}\n\n` : '') +
+    `**Usage:** \`${root.usage}\`\n\n` +
+    `### Global options\n\n${table(['Option', 'Description'], parseEntries(root.sections['Options']))}\n` +
+    `### Commands\n\n| Command | Description |\n| --- | --- |\n` +
+    commandEntries
+      .map((e) => {
+        const name = e.term.split(' ')[0];
+        return `| [\`${name}\`](#${anchor(name)}) | ${cell(e.desc)} |`;
+      })
+      .join('\n') +
+    '\n';
+
+  // ── Per-command detail ──
+  let details = `\n## Command reference\n`;
+  for (const cmd of program.commands) {
+    const name = cmd._name;
+    if (name === 'help') continue;
+    const cmdHelp = parseHelp(help(name));
+    details +=
+      `\n### underpost ${name}\n\n` +
+      (cmdHelp.description ? `${cmdHelp.description.replace(/\s+/g, ' ')}\n\n` : '') +
+      `**Usage:** \`${cmdHelp.usage}\`\n` +
+      detailSection(cmdHelp.sections, 'Arguments', ['Argument', 'Description']) +
+      detailSection(cmdHelp.sections, 'Options', ['Option', 'Description']) +
+      `\n---\n`;
+  }
+
+  const md = `${index}${details}`.replaceAll(oldVersion, newVersion);
   fs.writeFileSync(`./src/client/public/nexodev/docs/references/Command Line Interface.md`, md, 'utf8');
   fs.writeFileSync(`./CLI-HELP.md`, md, 'utf8');
 
-  // Update README.md: replace version and CLI index section between comment tags
-  let readme = fs.readFileSync(`./README.md`, 'utf8');
-  readme = readme.replaceAll(oldVersion, newVersion);
+  // Update README.md: bump version and refresh the CLI index between the comment tags.
+  let readme = fs.readFileSync(`./README.md`, 'utf8').replaceAll(oldVersion, newVersion);
   const cliStartTag = '<!-- cli-index-start -->';
   const cliEndTag = '<!-- cli-index-end -->';
   const startIdx = readme.indexOf(cliStartTag);
   const endIdx = readme.indexOf(cliEndTag);
   if (startIdx !== -1 && endIdx !== -1) {
+    const readmeIndex = index.replace(/\(#(underpost-[a-z0-9-]+)\)/g, '(CLI-HELP.md#$1)');
     readme =
       readme.substring(0, startIdx) +
       cliStartTag +
       '\n' +
-      baseOptions +
+      readmeIndex.replaceAll(oldVersion, newVersion) +
       '\n' +
       cliEndTag +
       readme.substring(endIdx + cliEndTag.length);
@@ -1746,6 +1775,331 @@ const loadConfServerJson = (jsonPath, options) => {
   return options && options.resolve === true ? resolveConfSecrets(raw) : raw;
 };
 
+/**
+ * Creates and writes the /etc/hosts file for a deployment.
+ * @method etcHostFactory
+ * @param {Array<string>} hosts - List of hosts to be added to the hosts file.
+ * @param {object} options - Options for the hosts file creation.
+ * @param {boolean} options.append - Whether to append to the existing hosts file.
+ * @returns {object} - Object containing the rendered hosts file.
+ * @memberof ServerConfBuilder
+ */
+const etcHostFactory = (hosts = [], options = { append: false }) => {
+  hosts = hosts.map((host) => {
+    try {
+      if (!host.startsWith('http')) host = `http://${host}`;
+      const hostname = new URL(host).hostname;
+      logger.info('Hostname extract valid', { host, hostname });
+      return hostname;
+    } catch (e) {
+      logger.warn('No hostname extract valid', host);
+      return host;
+    }
+  });
+  const renderHosts = `127.0.0.1         ${hosts.join(
+    ' ',
+  )} localhost localhost.localdomain localhost4 localhost4.localdomain4
+::1         localhost localhost.localdomain localhost6 localhost6.localdomain6`;
+
+  if (options && options.append && fs.existsSync(`/etc/hosts`)) {
+    fs.writeFileSync(
+      `/etc/hosts`,
+      fs.readFileSync(`/etc/hosts`, 'utf8') +
+        `
+${renderHosts}`,
+      'utf8',
+    );
+  } else fs.writeFileSync(`/etc/hosts`, renderHosts, 'utf8');
+  return { renderHosts };
+};
+
+/**
+ * Resolves the concrete deploy ids a build or conf-sync run should iterate over.
+ *
+ * The meta deploy id `dd` fans out to the comma separated ids declared in
+ * `engine-private/deploy/dd.router`; any other value is parsed as a comma separated list.
+ * Entries are trimmed and empties dropped.
+ *
+ * @method resolveDeployList
+ * @param {string} deployId - A deploy id, a comma separated list, or the `dd` meta id.
+ * @returns {string[]} Ordered list of concrete deploy ids.
+ * @memberof ServerConfBuilder
+ */
+const resolveDeployList = (deployId) =>
+  (deployId === 'dd' ? fs.readFileSync('./engine-private/deploy/dd.router', 'utf8') : deployId)
+    .split(',')
+    .map((id) => id.trim())
+    .filter(Boolean);
+
+/**
+ * Syncs a single deploy id's private configuration into its dedicated
+ * `engine-<suffix>-private` repository and pushes the result.
+ *
+ * Idempotent and safe to rerun: the private repo is cloned when missing or reset to a clean
+ * checkout when present, then the deploy id's `conf` folder, matching `replica` and
+ * `itc-scripts` entries, and any caller-supplied `extraPaths` payloads are mirrored. The
+ * commit/push step is a no-op when nothing changed (`silentOnError`).
+ *
+ * @method syncPrivateConf
+ * @param {string} deployId - A concrete deploy id (e.g. `dd-cyberia`), not the `dd` meta id.
+ * @param {string[]} [extraPaths=[]] - Extra `./engine-private` payload paths to mirror (from the
+ *   deploy's product catalog), kept out of this module so it stays product-agnostic.
+ * @returns {void}
+ * @memberof ServerConfBuilder
+ */
+const syncPrivateConf = (deployId, extraPaths = []) => {
+  const suffix = deployId.split('dd-')[1];
+  const privateRepoName = `engine-${suffix}-private`;
+  const privateGitUri = `${process.env.GITHUB_USERNAME}/${privateRepoName}`;
+  const privateRepoPath = `../${privateRepoName}`;
+
+  if (!fs.existsSync(privateRepoPath)) {
+    shellExec(`cd .. && underpost clone ${privateGitUri}`, { silent: true });
+  } else {
+    shellExec(`git config --global --add safe.directory '${dir.resolve(privateRepoPath)}'`);
+    shellExec(`cd ${privateRepoPath} && git checkout . && git clean -f -d && underpost pull . ${privateGitUri}`, {
+      silent: true,
+    });
+  }
+
+  const confDest = `${privateRepoPath}/conf/${deployId}`;
+  fs.removeSync(confDest);
+  fs.mkdirSync(confDest, { recursive: true });
+  fs.copySync(`./engine-private/conf/${deployId}`, confDest);
+
+  fs.removeSync(`${privateRepoPath}/replica`);
+  for (const payloadDir of ['replica', 'itc-scripts']) {
+    const srcDir = `./engine-private/${payloadDir}`;
+    if (!fs.existsSync(srcDir)) continue;
+    for (const entry of fs.readdirSync(srcDir))
+      if (entry.match(deployId)) fs.copySync(`${srcDir}/${entry}`, `${privateRepoPath}/${payloadDir}/${entry}`);
+  }
+
+  for (const extraPath of extraPaths) fs.copySync(`./engine-private/${extraPath}`, `${privateRepoPath}/${extraPath}`);
+
+  shellExec(
+    `cd ${privateRepoPath}` +
+      ` && git add .` +
+      ` && underpost cmt . ci engine-core-conf 'Update ${deployId} conf'` +
+      ` && underpost push . ${privateGitUri}`,
+    { silent: true, silentOnError: true },
+  );
+};
+
+/**
+ * Moves a deploy's public template sources into the engine working tree ahead of
+ * the build copy step. Idempotent and safe to rerun: each move is guarded by
+ * `existsSync`, so already-moved or absent sources are skipped rather than throwing.
+ * The `[src, dest]` pairs come from the deploy's product catalog (passed in), so
+ * this module stays product-agnostic.
+ *
+ * @method syncDeployIdSources
+ * @param {Array<[string, string]>} [sourceMoves=[]] - Public `[src, dest]` move pairs.
+ * @returns {boolean} `true` when any sources were declared, else `false`.
+ * @memberof ServerConfBuilder
+ */
+const syncDeployIdSources = (sourceMoves = []) => {
+  if (!sourceMoves.length) return false;
+  for (const dir of ['src/api', 'src/client/components', 'src/client/public', 'src/client/services'])
+    fs.mkdirSync(dir, { recursive: true });
+  for (const [src, dest] of sourceMoves) if (fs.existsSync(src)) fs.moveSync(src, dest, { overwrite: true });
+  return true;
+};
+
+/**
+ * Rebuilds the standalone `pwa-microservices-template` from scratch out of the current
+ * engine source tree.
+ *
+ * Clones the template repo next to the engine when missing, otherwise resets it to a clean
+ * pristine checkout, then syncs every engine-tracked file the template is allowed to carry
+ * ({@link validateTemplatePath}), strips engine-only + product modules, restores the template's
+ * own CI workflows + guest services, and rewrites `package.json` / `package-lock.json` / `README`
+ * so the result is a standalone, installable project. Throws on failure; callers own exit codes.
+ *
+ * Product catalogs are read dynamically ({@link module:src/server/catalog} `loadProductCatalogs`),
+ * so this stays decoupled from — and survives removal of — any product module.
+ *
+ * @method buildTemplate
+ * @param {object} [options]
+ * @param {string} [options.srcPath='./'] - Engine source root to sync from.
+ * @param {string} [options.toPath='../pwa-microservices-template'] - Template output path.
+ * @returns {Promise<void>}
+ * @memberof ServerConfBuilder
+ */
+const buildTemplate = async ({ srcPath = './', toPath = '../pwa-microservices-template' } = {}) => {
+  const walk = (await import('ignore-walk')).default;
+  const { TEMPLATE_RESTORE_PATHS, TEMPLATE_KEYWORDS, TEMPLATE_DESCRIPTION } = await import('./catalog-underpost.js');
+  const { loadProductCatalogs } = await import('./catalog.js');
+  const githubUsername = process.env.GITHUB_USERNAME;
+
+  logger.info('Build template', { srcPath, toPath });
+
+  const sourceFiles = (
+    await new Promise((resolve) =>
+      walk({ path: srcPath, ignoreFiles: [`.gitignore`], includeEmpty: false, follow: false }, (...args) =>
+        resolve(args[1]),
+      ),
+    )
+  ).filter((p) => !p.startsWith('.git'));
+
+  fs.removeSync(`${githubUsername}/pwa-microservices-template`);
+  shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
+
+  shellExec(`cd ${toPath} && git config core.filemode false`);
+
+  for (const copyPath of sourceFiles) {
+    if (copyPath === 'NaN') continue;
+    const absolutePath = `${srcPath}/${copyPath}`;
+    if (!validateTemplatePath(absolutePath)) continue;
+
+    const folder = getDirname(`${toPath}/${copyPath}`);
+    if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+
+    logger.info('build', `${toPath}/${copyPath}`);
+    fs.copyFileSync(absolutePath, `${toPath}/${copyPath}`);
+  }
+
+  fs.copySync(`./.vscode`, `${toPath}/.vscode`);
+  fs.copySync(`./src/client/public/default`, `${toPath}/src/client/public/default`);
+
+  // Preserve the template's own README + package.json identity before merging engine metadata.
+  for (const checkoutPath of ['README.md', 'package.json']) shellExec(`cd ${toPath} && git checkout ${checkoutPath}`);
+
+  // Strip each product catalog's `stripPaths` (aggregated dynamically) plus the engine-only
+  // workflows, deploy manifests, and product catalog modules.
+  const productStripPaths = (await loadProductCatalogs()).flatMap((c) => c.stripPaths);
+  for (const deletePath of productStripPaths) {
+    const target = `${toPath}/${deletePath}`;
+    if (fs.existsSync(target)) fs.removeSync(target);
+  }
+  shellExec(`rm -rf ${toPath}/.github`);
+  shellExec(`rm -rf ${toPath}/manifests/deployment/dd-*`);
+  shellExec(`rm -rf ${toPath}/src/server/catalog-*`);
+
+  fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
+  for (const restorePath of TEMPLATE_RESTORE_PATHS) {
+    const dest = `${toPath}/${restorePath}`;
+    if (fs.statSync(restorePath).isDirectory()) fs.copySync(restorePath, dest, { overwrite: true });
+    else fs.copyFileSync(restorePath, dest);
+  }
+
+  // ── package.json: take engine deps/scripts/version, keep template identity. ──
+  const originPackageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+  const templatePackageJson = JSON.parse(fs.readFileSync(`${toPath}/package.json`, 'utf8'));
+  const templateName = templatePackageJson.name;
+
+  templatePackageJson.dependencies = originPackageJson.dependencies;
+  templatePackageJson.devDependencies = originPackageJson.devDependencies;
+  templatePackageJson.version = originPackageJson.version;
+  templatePackageJson.scripts = originPackageJson.scripts;
+  templatePackageJson.overrides = originPackageJson.overrides;
+  templatePackageJson.name = templateName;
+  templatePackageJson.description = TEMPLATE_DESCRIPTION;
+  templatePackageJson.keywords = TEMPLATE_KEYWORDS;
+  delete templatePackageJson.scripts['build:template'];
+  fs.writeFileSync(`${toPath}/package.json`, JSON.stringify(templatePackageJson, null, 4), 'utf8');
+
+  // ── package-lock.json: mirror engine packages, keep template name/version on the root entry. ──
+  const originPackageLockJson = JSON.parse(fs.readFileSync('./package-lock.json', 'utf8'));
+  const templatePackageLockJson = JSON.parse(fs.readFileSync(`${toPath}/package-lock.json`, 'utf8'));
+  const originBasePackageLock = newInstance(templatePackageLockJson.packages['']);
+  templatePackageLockJson.name = templateName;
+  templatePackageLockJson.version = originPackageLockJson.version;
+  templatePackageLockJson.packages = originPackageLockJson.packages;
+  templatePackageLockJson.packages[''].name = templateName;
+  templatePackageLockJson.packages[''].version = originPackageLockJson.version;
+  templatePackageLockJson.packages[''].hasInstallScript = originBasePackageLock.hasInstallScript;
+  templatePackageLockJson.packages[''].license = originBasePackageLock.license;
+  fs.writeFileSync(`${toPath}/package-lock.json`, JSON.stringify(templatePackageLockJson, null, 4), 'utf8');
+
+  fs.writeFileSync(
+    `${toPath}/README.md`,
+    fs
+      .readFileSync('./README.md', 'utf8')
+      .replace('<!-- template-title -->', '#### Base template for pwa/api-rest projects.'),
+    'utf8',
+  );
+};
+
+const updatePrivateTemplateRepo = async () => {
+  const templatePath = '/home/dd/pwa-microservices-template';
+  shellExec(`sudo rm -rf ${templatePath}
+cd /home/dd/engine && npm run build:template
+cd /home/dd
+underpost clone --bare underpostnet/pwa-microservices-template-private
+sudo rm -rf ${templatePath}/.git
+mv ./pwa-microservices-template-private.git ${templatePath}/.git
+cd ${templatePath}
+npm install --omit=dev --ignore-scripts
+git init
+git config user.name 'underpostnet'
+git config user.email 'development@underpost.net'
+git add .`);
+  const hasChanges = shellExec(`node bin cmt ${templatePath} --has-changes`, {
+    stdout: true,
+    silent: true,
+    disableLog: true,
+  }).trim();
+  if (hasChanges === '1') {
+    shellExec(
+      `cd ${templatePath} && git commit -m 'Update template' && underpost push . underpostnet/pwa-microservices-template-private`,
+    );
+  }
+};
+
+/**
+ * @method updatePrivateEngineTestRepo
+ * @description Publishes a deploy id's freshly assembled template to its private
+ * **test** source repo `engine-test-<idPart>` (separate from the production
+ * `engine-<idPart>`). A pod started with `underpost start --build --private-test-repo`
+ * clones this repo, so work-in-progress engine source can be tested end to end
+ * without touching the production source. Mirrors {@link updatePrivateTemplateRepo}
+ * but per-deploy-id and against the test repo.
+ *
+ * Assumes the deploy id template has already been assembled at the template path
+ * (run `node bin/build <deployId>` first, or use `node bin/build <deployId> --update-private`).
+ * @param {string} deployId - Concrete deploy id (e.g. `dd-core`).
+ * @returns {Promise<void>}
+ * @memberof ServerConfBuilder
+ */
+const updatePrivateEngineTestRepo = async (deployId) => {
+  const username = process.env.GITHUB_USERNAME || 'underpostnet';
+  const repoName = `engine-test-${deployId.split('-')[1]}`;
+  const templatePath = '/home/dd/pwa-microservices-template';
+  if (!fs.existsSync(templatePath))
+    throw new Error(`updatePrivateEngineTestRepo: assemble the template first (node bin/build ${deployId})`);
+
+  // Detach the assembled working tree from any engine-build git history.
+  shellExec(`sudo rm -rf ${templatePath}/.git`);
+
+  // Adopt the test repo's existing history when present (so the push is a delta);
+  // otherwise publish a fresh history on first push.
+  shellExec(`cd /home/dd && sudo rm -rf ./${repoName}.git && underpost clone --bare ${username}/${repoName}`, {
+    silent: true,
+    disableLog: true,
+    silentOnError: true,
+  });
+  if (fs.existsSync(`/home/dd/${repoName}.git`)) shellExec(`mv /home/dd/${repoName}.git ${templatePath}/.git`);
+
+  // `git init` converts the moved bare repo into a normal work-tree repo (bare
+  // clones have no work tree, so `git add` would fail), and bootstraps a fresh
+  // repo on first publish. Idempotent — mirrors updatePrivateTemplateRepo.
+  shellExec(`cd ${templatePath}
+git init
+git config user.name '${username}'
+git config user.email 'development@underpost.net'
+git add .`);
+
+  const hasChanges = shellExec(`node bin cmt ${templatePath} --has-changes`, {
+    stdout: true,
+    silent: true,
+    disableLog: true,
+  }).trim();
+  if (hasChanges === '1')
+    shellExec(`cd ${templatePath} && git commit -m 'Update ${repoName}' && underpost push . ${username}/${repoName}`);
+  else logger.info('No changes to publish', { repoName });
+};
+
 export {
   Config,
   loadConf,
@@ -1774,7 +2128,6 @@ export {
   pathPortAssignmentFactory,
   deployRangePortFactory,
   awaitDeployMonitor,
-  rebuildConfFactory,
   buildCliDoc,
   getInstanceContext,
   buildApiConf,
@@ -1784,6 +2137,7 @@ export {
   devProxyHostFactory,
   isTlsDevProxy,
   getTlsHosts,
+  resolveHostKeyContext,
   resolveConfSecrets,
   loadConfServerJson,
   getConfFolder,
@@ -1792,4 +2146,11 @@ export {
   DEFAULT_DEPLOY_ID,
   loadCronDeployEnv,
   cronDeployIdResolve,
+  etcHostFactory,
+  resolveDeployList,
+  syncPrivateConf,
+  syncDeployIdSources,
+  buildTemplate,
+  updatePrivateTemplateRepo,
+  updatePrivateEngineTestRepo,
 };