underpost 3.2.12 → 3.2.21

package/README.md

@@ -16,7 +16,7 @@
 
 <div align="center">
 
-[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.12)](https://socket.dev/npm/package/underpost/overview/3.2.12) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
+[![Node.js CI](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/docker-image.ci.yml) [![Test](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml/badge.svg?branch=master)](https://github.com/underpostnet/engine/actions/workflows/coverall.ci.yml) [![Downloads](https://img.shields.io/npm/dm/underpost.svg)](https://www.npmjs.com/package/underpost) [![](https://data.jsdelivr.com/v1/package/npm/underpost/badge)](https://www.jsdelivr.com/package/npm/underpost) [![Socket Badge](https://socket.dev/api/badge/npm/package/underpost/3.2.21)](https://socket.dev/npm/package/underpost/overview/3.2.21) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine/badge.svg?branch=master)](https://coveralls.io/github/underpostnet/engine?branch=master) [![Version](https://img.shields.io/npm/v/underpost.svg)](https://www.npmjs.org/package/underpost) [![License](https://img.shields.io/npm/l/underpost.svg)](https://www.npmjs.com/package/underpost)
 
 </div>
 
@@ -86,46 +86,52 @@ npm run dev
 <a target="_top" href="https://www.nexodev.org/docs?cid=src">See Docs.</a>
 
 <!-- cli-index-start -->
-## underpost ci/cd cli v3.2.12
-
-### Usage: `underpost [options] [command]`
-  ```
- Options:
-  -V, --version                                              output the version number
-  -h, --help                                                 display help for command
-
-Commands:
-  new [options] [app-name]                                   Initializes a new Underpost project, service, or configuration.
-  client [options] [deploy-id] [sub-conf] [host] [path]      Builds client assets, single replicas, and/or syncs environment ports.
-  start [options] <deploy-id> [env]                          Initiates application servers, build pipelines, or other defined services based on the deployment ID.
-  clone [options] <uri>                                      Clones a specified GitHub repository into the current directory.
-  pull [options] <path> <uri>                                Pulls the latest changes from a specified GitHub repository.
-  cmt [options] [path] [commit-type] [module-tag] [message]  Manages commits to a GitHub repository, supporting various commit types and options.
-  push [options] <path> <uri>                                Pushes committed changes from a local repository to a remote GitHub repository.
-  env [deploy-id] [env] [subConf]                            Sets environment variables and configurations related to a specific deployment ID.
-  static [options]                                           Manages static build of page, bundles, and documentation with comprehensive customization options.
-  config [options] <operator> [key] [value]                  Manages Underpost configurations using various operators.
-  root                                                       Displays the root path of the npm installation.
-  ip [options] [ips]                                         Displays the current public machine IP addresses.
-  cluster [options] [pod-name]                               Manages Kubernetes clusters, defaulting to Kind cluster initialization.
-  deploy [options] [deploy-list] [env]                       Manages application deployments, defaulting to deploying development pods.
-  secret [options] <platform>                                Manages secrets for various platforms.
-  image [options]                                            Manages Docker images, including building, saving, and loading into Kubernetes clusters.
-  install                                                    Quickly imports Underpost npm dependencies by copying them.
-  db [options] [deploy-list]                                 Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration.
-  metadata [options] [deploy-id] [host] [path]               Manages cluster metadata operations, including import and export.
-  cron [options] [deploy-list] [job-list]                    Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests.
-  fs [options] [path]                                        Manages file storage, defaulting to file upload operations.
-  test [options] [deploy-list]                               Manages and runs tests, defaulting to the current Underpost default test suite.
-  monitor [options] <deploy-id> [env]                        Manages health server monitoring for specified deployments.
-  ssh [options]                                              Manages SSH credentials and sessions for remote access to cluster nodes or services.
-  run [options] <runner-id> [path]                           Runs specified scripts using various runners.
-  lxd [options] [vm-id]                                      Manages LXD virtual machines as K3s nodes (control plane or workers).
-  baremetal [options] [workflow-id]                          Manages baremetal server operations, including installation, database setup, commissioning, and user management.
-  release [options] [version]                                Release orchestrator for building new versions and deploying releases of the Underpost CLI.
-  help [command]                                             display help for command
- 
-```
+## Underpost CLI
+
+> underpost ci/cd cli v3.2.21
+
+**Usage:** `underpost [options] [command]`
+
+### Global options
+
+| Option | Description |
+| --- | --- |
+| `-V, --version` | output the version number |
+| `-h, --help` | display help for command |
+
+### Commands
+
+| Command | Description |
+| --- | --- |
+| [`new`](CLI-HELP.md#underpost-new) | Initializes a new Underpost project, service, or configuration. |
+| [`client`](CLI-HELP.md#underpost-client) | Builds client assets, single replicas, and/or syncs environment ports. |
+| [`start`](CLI-HELP.md#underpost-start) | Initiates application servers, build pipelines, or other defined services based on the deployment ID. |
+| [`clone`](CLI-HELP.md#underpost-clone) | Clones a specified GitHub repository into the current directory. |
+| [`pull`](CLI-HELP.md#underpost-pull) | Pulls the latest changes from a specified GitHub repository. |
+| [`cmt`](CLI-HELP.md#underpost-cmt) | Manages commits to a GitHub repository, supporting various commit types and options. |
+| [`push`](CLI-HELP.md#underpost-push) | Pushes committed changes from a local repository to a remote GitHub repository. |
+| [`env`](CLI-HELP.md#underpost-env) | Sets environment variables and configurations related to a specific deployment ID. |
+| [`static`](CLI-HELP.md#underpost-static) | Manages static build of page, bundles, and documentation with comprehensive customization options. |
+| [`config`](CLI-HELP.md#underpost-config) | Manages Underpost configurations using various operators. |
+| [`root`](CLI-HELP.md#underpost-root) | Displays the root path of the npm installation. |
+| [`ip`](CLI-HELP.md#underpost-ip) | Displays the current public machine IP addresses. |
+| [`cluster`](CLI-HELP.md#underpost-cluster) | Manages Kubernetes clusters, defaulting to Kind cluster initialization. |
+| [`deploy`](CLI-HELP.md#underpost-deploy) | Manages application deployments, defaulting to deploying development pods. |
+| [`secret`](CLI-HELP.md#underpost-secret) | Manages secrets for various platforms. |
+| [`image`](CLI-HELP.md#underpost-image) | Manages Docker images, including building, saving, and loading into Kubernetes clusters. |
+| [`install`](CLI-HELP.md#underpost-install) | Quickly imports Underpost npm dependencies by copying them. |
+| [`db`](CLI-HELP.md#underpost-db) | Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration. |
+| [`metadata`](CLI-HELP.md#underpost-metadata) | Manages cluster metadata operations, including import and export. |
+| [`cron`](CLI-HELP.md#underpost-cron) | Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests. |
+| [`fs`](CLI-HELP.md#underpost-fs) | Manages file storage, defaulting to file upload operations. |
+| [`test`](CLI-HELP.md#underpost-test) | Manages and runs tests, defaulting to the current Underpost default test suite. |
+| [`monitor`](CLI-HELP.md#underpost-monitor) | Manages health server monitoring for specified deployments. |
+| [`ssh`](CLI-HELP.md#underpost-ssh) | Manages SSH credentials and sessions for remote access to cluster nodes or services. |
+| [`run`](CLI-HELP.md#underpost-run) | Runs specified scripts using various runners. |
+| [`lxd`](CLI-HELP.md#underpost-lxd) | Manages LXD virtual machines as K3s nodes (control plane or workers). |
+| [`baremetal`](CLI-HELP.md#underpost-baremetal) | Manages baremetal server operations, including installation, database setup, commissioning, and user management. |
+| [`release`](CLI-HELP.md#underpost-release) | Release orchestrator for building new versions and deploying releases of the Underpost CLI. |
+
 <!-- cli-index-end -->
 
 <a target="_top" href="https://github.com/underpostnet/pwa-microservices-template/blob/master/CLI-HELP.md">See CLI Docs.</a>

package/bin/build.js

@@ -1,105 +1,64 @@
+#! /usr/bin/env node
+
+import { Command } from 'commander';
 import fs from 'fs-extra';
-import { loggerFactory } from '../src/server/logger.js';
-import { shellExec } from '../src/server/process.js';
 import dotenv from 'dotenv';
+import { loggerFactory } from '../src/server/logger.js';
 import { getCapVariableName } from '../src/client/components/core/CommonJs.js';
-import { getPathsSSR } from '../src/server/conf.js';
+import {
+  getPathsSSR,
+  resolveDeployList,
+  syncPrivateConf,
+  syncDeployIdSources,
+  buildTemplate,
+} from '../src/server/conf.js';
+import { loadDeployCatalog } from '../src/server/catalog.js';
+import UnderpostRepository from '../src/cli/repository.js';
 
 const baseConfPath = './engine-private/conf/dd-cron/.env.production';
 if (fs.existsSync(baseConfPath)) dotenv.config({ path: baseConfPath, override: true });
 
 const logger = loggerFactory(import.meta);
 
-const confName = process.argv[2];
 const basePath = '../pwa-microservices-template';
-const repoName = `engine-${confName.split('dd-')[1]}`;
-const deployList = (confName === 'dd' ? fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8') : confName).split(
-  ',',
-);
-
-logger.info('Build repository', {
-  confName,
-  repoName,
-  basePath,
-  deployList,
-});
-
-if (process.argv.includes('conf')) {
-  for (const _confName of deployList) {
-    const _repoName = `engine-${_confName.split('dd-')[1]}`;
-    const privateRepoName = `${_repoName}-private`;
-    const privateGitUri = `${process.env.GITHUB_USERNAME}/${privateRepoName}`;
-
-    if (!fs.existsSync(`../${privateRepoName}`)) {
-      shellExec(`cd .. && underpost clone ${privateGitUri}`, { silent: true });
-    } else {
-      shellExec(`cd ../${privateRepoName} && git checkout . && git clean -f -d && underpost pull . ${privateGitUri}`, {
-        silent: true,
-      });
-    }
-    const toPath = `../${privateRepoName}/conf/${_confName}`;
-    fs.removeSync(toPath);
-    fs.mkdirSync(toPath, { recursive: true });
-    fs.copySync(`./engine-private/conf/${_confName}`, toPath);
-    fs.removeSync(`../${privateRepoName}/replica`);
-    if (fs.existsSync(`./engine-private/replica`)) {
-      const replicas = await fs.readdir(`./engine-private/replica`);
-      for (const replica of replicas)
-        if (replica.match(_confName))
-          fs.copySync(`./engine-private/replica/${replica}`, `../${privateRepoName}/replica/${replica}`);
-    }
 
-    if (fs.existsSync(`./engine-private/itc-scripts`)) {
-      const itcScripts = await fs.readdir(`./engine-private/itc-scripts`);
-      for (const itcScript of itcScripts)
-        if (itcScript.match(_confName))
-          fs.copySync(`./engine-private/itc-scripts/${itcScript}`, `../${privateRepoName}/itc-scripts/${itcScript}`);
-    }
-    switch (_confName) {
-      case 'dd-cyberia':
-        fs.copySync(`./engine-private/cyberia-instances/FOREST`, `../${privateRepoName}/cyberia-instances/FOREST`);
-        break;
-      default:
-        break;
-    }
-    shellExec(
-      `cd ../${privateRepoName}` +
-        ` && git add .` +
-        ` && underpost cmt . ci engine-core-conf 'Update ${_confName} conf'` +
-        ` && underpost push . ${privateGitUri}`,
-      {
-        silent: true,
-        silentOnError: true,
-      },
-    );
+/**
+ * Assembles a single deploy id's public template under {@link basePath}: pulls in
+ * its deploy-id-specific public sources, then mirrors the APIs, client components,
+ * SSR assets, manifests, and packaging declared by its conf into the template repo.
+ * @param {string} confName - A concrete deploy id (e.g. `dd-prototype`).
+ */
+const buildDeployTemplate = async (confName) => {
+  const repoName = `engine-${confName.split('dd-')[1]}`;
+  const catalog = await loadDeployCatalog(confName);
+
+  if (catalog.sourceMoves.length) {
+    UnderpostRepository.API.sparseCheckoutDirectory(`conf/${confName}`);
+    if (catalog.sourceMoves.some(([src]) => !fs.existsSync(src))) UnderpostRepository.API.pullSourceRepo(repoName);
   }
-  process.exit(0);
-}
+  syncDeployIdSources(catalog.sourceMoves);
 
-if (confName === 'dd') {
-  for (const _confName of deployList) {
-    shellExec(`node bin/build ${_confName}`);
-  }
-  process.exit(0);
-}
+  const confDir = `./engine-private/conf/${confName}`;
+  const DefaultConf = {
+    server: JSON.parse(fs.readFileSync(`${confDir}/conf.server.json`, 'utf8')),
+    client: JSON.parse(fs.readFileSync(`${confDir}/conf.client.json`, 'utf8')),
+    ssr: JSON.parse(fs.readFileSync(`${confDir}/conf.ssr.json`, 'utf8')),
+  };
 
-const { DefaultConf } = await import(`../conf.${confName}.js`);
-
-{
   for (const host of Object.keys(DefaultConf.server)) {
     for (const path of Object.keys(DefaultConf.server[host])) {
       const { apis, ws } = DefaultConf.server[host][path];
       if (apis)
         for (const api of apis) {
-          {
-            const originPath = `./src/api/${api}`;
-            logger.info(`Build`, originPath);
-            fs.copySync(originPath, `${basePath}/src/api/${api}`);
+          const apiSrc = `./src/api/${api}`;
+          if (fs.existsSync(apiSrc)) {
+            logger.info(`Build`, apiSrc);
+            fs.copySync(apiSrc, `${basePath}/src/api/${api}`);
           }
-          {
-            const originPath = `./src/client/services/${api}`;
-            logger.info(`Build`, originPath);
-            fs.copySync(originPath, `${basePath}/src/client/services/${api}`);
+          const serviceSrc = `./src/client/services/${api}`;
+          if (fs.existsSync(serviceSrc)) {
+            logger.info(`Build`, serviceSrc);
+            fs.copySync(serviceSrc, `${basePath}/src/client/services/${api}`);
           }
         }
 
@@ -108,9 +67,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       }
     }
   }
-}
 
-{
   for (const client of Object.keys(DefaultConf.client)) {
     const capName = getCapVariableName(client);
     for (const component of Object.keys(DefaultConf.client[client].components)) {
@@ -135,9 +92,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       }
     }
   }
-}
 
-{
   for (const client of Object.keys(DefaultConf.ssr)) {
     const ssrPaths = getPathsSSR(DefaultConf.ssr[client]);
     for (const originPath of ssrPaths) {
@@ -149,16 +104,14 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
   }
 
   if (!fs.existsSync(`${basePath}/.github/workflows`))
-    fs.mkdirSync(`${basePath}/.github/workflows`, {
-      recursive: true,
-    });
+    fs.mkdirSync(`${basePath}/.github/workflows`, { recursive: true });
 
   const originPackageJson = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
   const packageJson = JSON.parse(fs.readFileSync(`${basePath}/package.json`, 'utf8'));
   packageJson.name = repoName.replace('engine-', '');
 
   switch (confName) {
-    case 'dd-cyberia':
+    case 'dd-cyberia': {
       fs.copyFileSync(`./bin/cyberia.js`, `${basePath}/bin/cyberia.js`);
       fs.copyFileSync(
         `./.github/workflows/publish.cyberia.ci.yml`,
@@ -167,59 +120,24 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       if (packageJson.bin) delete packageJson.bin.underpost;
       if (!packageJson.bin) packageJson.bin = {};
       packageJson.bin.cyberia = 'bin/index.js';
-      packageJson.keywords = [
-        'cyberia',
-        'cyberia-cli',
-        'engine-cyberia',
-        'sidecar',
-        'data-layer',
-        'engine-cyberia',
-        'object-layer',
-        'atlas-sprite-sheet',
-        'ipfs',
-        'erc-1155',
-        'object-layer-token',
-        'hardhat',
-        'hyperledger-besu',
-        'blockchain',
-        'web3',
-        'underpost-platform',
-        'mmorpg',
-      ];
-      packageJson.description =
-        'Cyberia CLI — toolchain for the Cyberia MMO data layer, content pipeline, persistence, gRPC services, and ERC-1155 lifecycle on Hyperledger Besu.';
+      packageJson.keywords = catalog.keywords;
+      packageJson.description = catalog.description;
       const { CyberiaDependencies } = await import(`../src/api/cyberia-server-defaults/cyberia-server-defaults.js`);
       packageJson.dependencies = {
         ...originPackageJson.dependencies,
         ...CyberiaDependencies,
       };
       fs.writeFileSync(`${basePath}/bin/index.js`, fs.readFileSync(`./bin/cyberia.js`, 'utf8'), 'utf8');
+      // Canonical Cyberia doc; engine-cyberia/README.md is a generated copy — never hand-edited.
       fs.writeFileSync(
         `${basePath}/README.md`,
-        fs.readFileSync(`./src/client/public/cyberia-docs/CYBERIA-CLI.md`, 'utf8'),
+        fs.readFileSync(`./src/client/public/cyberia-docs/CYBERIA.md`, 'utf8'),
         'utf8',
       );
       fs.copySync(`./hardhat`, `${basePath}/hardhat`);
-      for (const path of [
-        '/src/grpc/cyberia',
-        '/src/client/ssr/views/CyberiaServerMetrics.js',
-        '/src/server/object-layer.js',
-        '/src/server/atlas-sprite-sheet-generator.js',
-        '/src/server/shape-generator.js',
-        '/src/server/semantic-layer-generator.js',
-        '/src/server/semantic-layer-generator-floor.js',
-        '/src/server/semantic-layer-generator-skin.js',
-        '/src/server/semantic-layer-generator-resource.js',
-        '/test/shape-generator.test.js',
-        '/src/server/besu-genesis-generator.js',
-        '/src/runtime/cyberia-server',
-        '/src/runtime/cyberia-client',
-        '/.github/workflows/hardhat.ci.yml',
-        '/src/client/public/cyberia-docs',
-        '/src/api/cyberia-server-defaults',
-      ])
-        fs.copySync(`.${path}`, `${basePath}${path}`);
-
+      for (const path of catalog.templatePaths) fs.copySync(`.${path}`, `${basePath}${path}`);
+      break;
+    }
     default:
       break;
   }
@@ -247,8 +165,6 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
       `${basePath}/manifests/deployment/${confName}-development`,
     );
 
-  // Copy conf.<deploy-id>.js to conf.js for the respective deployment
-  fs.copyFileSync(`./conf.${confName}.js`, `${basePath}/conf.js`);
   fs.copyFileSync(`./manifests/deployment/${confName}-development/proxy.yaml`, `${basePath}/proxy.yaml`);
   fs.copyFileSync(`./manifests/deployment/${confName}-development/deployment.yaml`, `${basePath}/deployment.yaml`);
   const pvPvcPath = `./manifests/deployment/${confName}-development/pv-pvc.yaml`;
@@ -257,6 +173,41 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
   if (fs.existsSync(`./src/ws/${confName.split('-')[1]}`)) {
     fs.copySync(`./src/ws/${confName.split('-')[1]}`, `${basePath}/src/ws/${confName.split('-')[1]}`);
   }
-  fs.copyFileSync(`.gitignore`, `${basePath}/.gitignore`);
-  shellExec(`cd ${basePath} && npm install --ignore-scripts`);
-}
+  fs.writeFileSync(
+    `${basePath}/.gitignore`,
+    fs.readFileSync(`.gitignore`, 'utf8').split('# Ignore ERP / CRM custom prototypes src')[0],
+  );
+};
+
+const program = new Command();
+
+program
+  .name('build')
+  .description('Assemble deploy id public templates and sync their private configuration repos.')
+  .argument('<conf-name>', 'Deploy id, comma-separated list, or the "dd" meta id (fans out via dd.router).')
+  .argument('[env]', 'Environment label (informational; kept for CI invocation compatibility).')
+  .option('--conf', 'Sync each deploy id private configuration repo and exit (no template assembly).')
+  .option(
+    '--no-template-rebuild',
+    'Skip the from-scratch base template reconstruction before assembly (assemble onto the existing template).',
+  )
+  .action(async (confName, env, options) => {
+    const deployList = resolveDeployList(confName);
+    logger.info('Build repository', { confName, basePath, deployList, conf: !!options.conf });
+
+    if (options.conf) {
+      for (const deployId of deployList) {
+        const { privateConfPaths } = await loadDeployCatalog(deployId);
+        syncPrivateConf(deployId, privateConfPaths);
+      }
+      return;
+    }
+
+    // Reconstruct the base template from 0 before assembly so no src from a previous
+    // build run leaks into this one. Opt out with --no-template-rebuild.
+    if (options.templateRebuild) await buildTemplate({ toPath: basePath });
+
+    for (const deployId of deployList) await buildDeployTemplate(deployId);
+  });
+
+await program.parseAsync();

package/bin/build.template.js

@@ -1,187 +1,33 @@
-import fs from 'fs-extra';
+#! /usr/bin/env node
 
-import { loggerFactory } from '../src/server/logger.js';
-import { getDirname, newInstance, uniqueArray } from '../src/client/components/core/CommonJs.js';
-import { shellExec } from '../src/server/process.js';
-import walk from 'ignore-walk';
-import { validateTemplatePath } from '../src/server/conf.js';
+import { Command } from 'commander';
+import fs from 'fs-extra';
 import dotenv from 'dotenv';
-
-const logger = loggerFactory(import.meta);
+import { loggerFactory } from '../src/server/logger.js';
+import { buildTemplate, updatePrivateTemplateRepo } from '../src/server/conf.js';
 
 if (fs.existsSync('./engine-private/conf/dd-cron/.env.production'))
-  dotenv.config({
-    path: `./engine-private/conf/dd-cron/.env.production`,
-    override: true,
-  });
+  dotenv.config({ path: `./engine-private/conf/dd-cron/.env.production`, override: true });
 else dotenv.config();
 
-// Engine-only paths stripped from the template after the source sync.
-const TEMPLATE_DELETE_PATHS = [
-  './.github',
-  './manifests/deployment/dd-lampp-development',
-  './manifests/deployment/dd-cyberia-development',
-  './manifests/deployment/dd-core-development',
-  './manifests/deployment/dd-template-development',
-  './src/server/object-layer.js',
-  './src/server/atlas-sprite-sheet-generator.js',
-  './src/server/shape-generator.js',
-  './src/server/semantic-layer-generator.js',
-  './src/server/semantic-layer-generator-floor.js',
-  './src/server/semantic-layer-generator-skin.js',
-  './src/server/semantic-layer-generator-resource.js',
-  './src/server/besu-genesis-generator.js',
-  './src/grpc/cyberia',
-  './src/runtime/cyberia-server',
-  './src/runtime/cyberia-client',
-  './test/shape-generator.test.js',
-  './src/client/public/cyberia-docs',
-  'bin/cyberia.js',
-  './hardhat',
-];
-
-// Workflow + service files re-added to the template after the engine-only strip above.
-const TEMPLATE_RESTORE_PATHS = [
-  `./.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',
-];
-
-const TEMPLATE_KEYWORDS = [
-  'underpost',
-  'underpost-platform',
-  'cli',
-  'toolchain',
-  'ci-cd',
-  'devops',
-  'kubernetes',
-  'k3s',
-  'kubeadm',
-  'lxd',
-  'bare-metal',
-  'container-orchestration',
-  'image-management',
-  'pwa',
-  'workbox',
-  'microservices',
-];
-
-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.';
-
-/**
- * Builds the pwa-microservices-template from scratch out of the current engine source tree.
- *
- * Clones (or resets) the template repo next to the engine, syncs every engine-tracked file the
- * template is allowed to carry (validateTemplatePath), strips engine-only modules, restores the
- * template's own CI workflows + guest services, and rewrites package.json / package-lock.json /
- * README so the template is a standalone, installable project.
- *
- * Usage: node bin/build.template [srcPath=./] [toPath=../pwa-microservices-template]
- */
-const srcPath = (process.argv[2] ?? './').replaceAll(`'`, '');
-const toPath = (process.argv[3] ?? '../pwa-microservices-template').replaceAll(`'`, '');
-const githubUsername = process.env.GITHUB_USERNAME;
-
-logger.info('Build template', { srcPath, toPath });
-
-try {
-  const sourceFiles = (
-    await new Promise((resolve) =>
-      walk(
-        {
-          path: srcPath,
-          ignoreFiles: [`.gitignore`],
-          includeEmpty: false,
-          follow: false,
-        },
-        (...args) => resolve(args[1]),
-      ),
-    )
-  ).filter((p) => !p.startsWith('.git'));
-
-  // Clone the template from 0 if missing; otherwise reset it to a clean pristine checkout.
-  if (!fs.existsSync(toPath)) {
-    shellExec(`cd .. && node engine/bin clone ${githubUsername}/pwa-microservices-template`);
-  } else {
-    shellExec(`cd ${toPath} && git reset && git checkout . && git clean -f -d`);
-    shellExec(`node bin pull ${toPath} ${githubUsername}/pwa-microservices-template`);
-    shellExec(`sudo rm -rf ${toPath}/engine-private`);
-    shellExec(`sudo rm -rf ${toPath}/logs`);
-  }
-  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}`);
-
-  for (const deletePath of TEMPLATE_DELETE_PATHS) {
-    const target = `${toPath}/${deletePath}`;
-    if (fs.existsSync(target)) fs.removeSync(target);
-  }
-
-  fs.mkdirSync(`${toPath}/.github/workflows`, { recursive: true });
-  for (const restorePath of TEMPLATE_RESTORE_PATHS) fs.copyFileSync(restorePath, `${toPath}/${restorePath}`);
-
-  // ── 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 = uniqueArray(TEMPLATE_KEYWORDS.concat(templatePackageJson.keywords || []));
-  delete templatePackageJson.scripts['update:template'];
-  fs.writeFileSync(`${toPath}/package.json`, JSON.stringify(templatePackageJson, null, 4), 'utf8');
+const logger = loggerFactory(import.meta);
 
-  // ── 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');
+const program = new Command();
+
+program
+  .name('build.template')
+  .description('Rebuild the standalone pwa-microservices-template from scratch out of the engine source tree.')
+  .argument('[src-path]', 'Engine source root to sync from.', './')
+  .argument('[to-path]', 'Template output path.', '../pwa-microservices-template')
+  .option('--update-private', 'Update private template repository', false)
+  .action(async (srcPath, toPath, options) => {
+    try {
+      if (options.updatePrivate) return await updatePrivateTemplateRepo();
+      await buildTemplate({ srcPath: srcPath.replaceAll(`'`, ''), toPath: toPath.replaceAll(`'`, '') });
+    } catch (error) {
+      logger.error(error, error.stack);
+      process.exit(1);
+    }
+  });
 
-  fs.writeFileSync(
-    `${toPath}/README.md`,
-    fs
-      .readFileSync('./README.md', 'utf8')
-      .replace('<!-- template-title -->', '#### Base template for pwa/api-rest projects.'),
-    'utf8',
-  );
-} catch (error) {
-  logger.error(error, error.stack);
-  process.exit(1);
-}
+await program.parseAsync();

package/bin/deploy.js

@@ -283,7 +283,10 @@ ${shellExec(`git log | grep Author: | sort -u`, { stdout: true }).split(`\n`).jo
     }
 
     case 'cli-docs': {
-      buildCliDoc(program, process.argv[3], process.argv[4]);
+      const version = Underpost.version;
+      const newVersion =
+        process.argv[4] && !process.argv[4].startsWith('v') ? `v${process.argv[4]}` : process.argv[4] || version;
+      buildCliDoc(program, process.argv[3] || version, newVersion);
       break;
     }