cyberia 3.2.12 → 3.2.22

package/bin/build.js

@@ -1,105 +1,65 @@
+#! /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,
+  updatePrivateEngineTestRepo,
+} 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,
-      },
-    );
-  }
-  process.exit(0);
-}
 
-if (confName === 'dd') {
-  for (const _confName of deployList) {
-    shellExec(`node bin/build ${_confName}`);
+/**
+ * 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);
 
-const { DefaultConf } = await import(`../conf.${confName}.js`);
+  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')),
+  };
 
-{
   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 +68,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 +93,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 +105,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,27 +121,8 @@ 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,
@@ -201,26 +136,9 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         '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;
   }
@@ -248,8 +166,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`;
@@ -258,6 +174,51 @@ 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).',
+  )
+  .option(
+    '--update-private',
+    'After assembling each deploy id, publish it to its private test source repo (underpostnet/engine-test-<id>) for isolated test deploys.',
+    false,
+  )
+  .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);
+      // Publish the just-assembled tree to the deploy id's private test repo so a
+      // pod started with `--private-test-repo` clones this work-in-progress source.
+      if (options.updatePrivate) await updatePrivateEngineTestRepo(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/cyberia.js

@@ -4131,6 +4131,10 @@ try {
   runner
     .command('import-default-items')
     .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
+    .option(
+      '--mongo-host <mongo-host>',
+      'Mongo host override (forwarded to ol, seed-skill-config, seed-dialogues, client-hints)',
+    )
     .description('Import default Object Layer items, skill config, dialogues, and client-hints into MongoDB')
     .action(async (options) => {
       // Pre-flight: every item id referenced by the fallback world must
@@ -4148,11 +4152,12 @@ try {
       }
 
       const devFlag = options.dev ? ' --dev' : '';
+      const mongoHostFlag = options.mongoHost ? ` --mongo-host ${options.mongoHost}` : '';
       const instanceCode = process.env.INSTANCE_CODE || 'cyberia-main';
-      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}`);
-      shellExec(`node bin/cyberia run-workflow seed-skill-config${devFlag}`);
-      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}`);
-      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}`);
+      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-skill-config${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}${mongoHostFlag}`);
     });
 
   runner
@@ -4407,7 +4412,7 @@ try {
     throw new Error('Trigger underpost passthrough');
   }
 
-  program.parse();
+  await program.parseAsync();
 } catch (error) {
   // ONLY reroute on the explicit passthrough sentinel. Any other thrown
   // error (subprocess non-zero from shellExec's fail-fast default, CLI
@@ -4420,7 +4425,7 @@ try {
     process.argv = process.argv.filter((c) => c !== 'underpost');
     logger.warn('Rerouting to underpost cli...');
     try {
-      underpostProgram.parse();
+      await underpostProgram.parseAsync();
     } catch (err) {
       logger.error(err);
       process.exit(1);

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;
     }
 

package/bin/index.js

@@ -4131,6 +4131,10 @@ try {
   runner
     .command('import-default-items')
     .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
+    .option(
+      '--mongo-host <mongo-host>',
+      'Mongo host override (forwarded to ol, seed-skill-config, seed-dialogues, client-hints)',
+    )
     .description('Import default Object Layer items, skill config, dialogues, and client-hints into MongoDB')
     .action(async (options) => {
       // Pre-flight: every item id referenced by the fallback world must
@@ -4148,11 +4152,12 @@ try {
       }
 
       const devFlag = options.dev ? ' --dev' : '';
+      const mongoHostFlag = options.mongoHost ? ` --mongo-host ${options.mongoHost}` : '';
       const instanceCode = process.env.INSTANCE_CODE || 'cyberia-main';
-      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}`);
-      shellExec(`node bin/cyberia run-workflow seed-skill-config${devFlag}`);
-      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}`);
-      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}`);
+      shellExec(`node bin/cyberia ol ${DefaultCyberiaItems.map((e) => e.item.id)} --import${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-skill-config${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia run-workflow seed-dialogues${devFlag}${mongoHostFlag}`);
+      shellExec(`node bin/cyberia client-hints ${instanceCode} --seed-defaults${devFlag}${mongoHostFlag}`);
     });
 
   runner
@@ -4407,7 +4412,7 @@ try {
     throw new Error('Trigger underpost passthrough');
   }
 
-  program.parse();
+  await program.parseAsync();
 } catch (error) {
   // ONLY reroute on the explicit passthrough sentinel. Any other thrown
   // error (subprocess non-zero from shellExec's fail-fast default, CLI
@@ -4420,7 +4425,7 @@ try {
     process.argv = process.argv.filter((c) => c !== 'underpost');
     logger.warn('Rerouting to underpost cli...');
     try {
-      underpostProgram.parse();
+      await underpostProgram.parseAsync();
     } catch (err) {
       logger.error(err);
       process.exit(1);

package/conf.js

@@ -750,6 +750,7 @@ const DefaultConf = /**/ {
           jsJsonPath: './typedoc.dd-cyberia.json',
           coverageOutputDir: 'hardhat-coverage',
           references: [
+            './src/client/public/cyberia-docs/CYBERIA.md',
             './src/client/public/cyberia-docs/WHITE-PAPER.md',
             './src/client/public/cyberia-docs/ARCHITECTURE.md',
             './src/client/public/cyberia-docs/QUEST-SYSTEM.md',