cyberia 3.2.9 → 3.2.22

package/bin/index.js

@@ -20,7 +20,7 @@ import stringify from 'fast-json-stable-stringify';
 import { shellExec } from '../src/server/process.js';
 import { loggerFactory } from '../src/server/logger.js';
 import { generateBesuManifests, deployBesu, removeBesu } from '../src/server/besu-genesis-generator.js';
-import { DataBaseProvider } from '../src/db/DataBaseProvider.js';
+import { DataBaseProviderService } from '../src/db/DataBaseProvider.js';
 import { loadConfServerJson } from '../src/server/conf.js';
 import {
   ObjectLayerEngine,
@@ -45,7 +45,7 @@ import {
   DefaultCyberiaDialogues,
   DefaultCyberiaActions,
   DefaultCyberiaQuests,
-} from '../src/client/components/cyberia-portal/CommonCyberiaPortal.js';
+} from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
 
 /**
  * Connect to the project MongoDB instance using the standard env / conf layout.
@@ -72,14 +72,14 @@ async function connectDbForChain({ envPath, mongoHost }) {
 
   db.host = mongoHost ? mongoHost : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
 
-  await DataBaseProvider.load({
+  await DataBaseProviderService.load({
     apis: ['object-layer'],
     host,
     path,
     db,
   });
 
-  const ObjectLayer = DataBaseProvider.instance[`${host}${path}`].mongoose.models.ObjectLayer;
+  const ObjectLayer = DataBaseProviderService.getModel('object-layer', { host, path });
   return { ObjectLayer, host, path };
 }
 
@@ -213,7 +213,7 @@ try {
           db,
         });
 
-        await DataBaseProvider.load({
+        await DataBaseProviderService.load({
           apis: ['object-layer', 'object-layer-render-frames', 'atlas-sprite-sheet', 'file', 'ipfs'],
           host,
           path,
@@ -221,16 +221,15 @@ try {
         });
 
         /** @type {import('mongoose').Model} */
-        const ObjectLayer = DataBaseProvider.instance[`${host}${path}`].mongoose.models.ObjectLayer;
+        const ObjectLayer = DataBaseProviderService.getModel('object-layer', { host, path });
         /** @type {import('mongoose').Model} */
-        const ObjectLayerRenderFrames =
-          DataBaseProvider.instance[`${host}${path}`].mongoose.models.ObjectLayerRenderFrames;
+        const ObjectLayerRenderFrames = DataBaseProviderService.getModel('object-layer-render-frames', { host, path });
         /** @type {import('mongoose').Model} */
-        const AtlasSpriteSheet = DataBaseProvider.instance[`${host}${path}`].mongoose.models.AtlasSpriteSheet;
+        const AtlasSpriteSheet = DataBaseProviderService.getModel('atlas-sprite-sheet', { host, path });
         /** @type {import('mongoose').Model} */
-        const File = DataBaseProvider.instance[`${host}${path}`].mongoose.models.File;
+        const File = DataBaseProviderService.getModel('file', { host, path });
         /** @type {import('mongoose').Model} */
-        const Ipfs = DataBaseProvider.instance[`${host}${path}`].mongoose.models.Ipfs;
+        const Ipfs = DataBaseProviderService.getModel('ipfs', { host, path });
 
         if (options.drop) {
           // Parse comma-separated item IDs for targeted drop; if none provided, drop everything
@@ -1694,7 +1693,7 @@ try {
           }
         }
 
-        await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+        await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
       },
     )
     .description('Object layer management');
@@ -1749,7 +1748,7 @@ try {
 
       logger.info('instance env', { env: options.envPath, deployId, host, path, db });
 
-      await DataBaseProvider.load({
+      await DataBaseProviderService.load({
         apis: [
           'cyberia-instance',
           'cyberia-instance-conf',
@@ -1767,16 +1766,15 @@ try {
         db,
       });
 
-      const dbModels = DataBaseProvider.instance[`${host}${path}`].mongoose.models;
-      const CyberiaInstance = dbModels.CyberiaInstance;
-      const CyberiaInstanceConf = dbModels.CyberiaInstanceConf;
-      const CyberiaDialogue = dbModels.CyberiaDialogue;
-      const CyberiaMap = dbModels.CyberiaMap;
-      const ObjectLayer = dbModels.ObjectLayer;
-      const ObjectLayerRenderFrames = dbModels.ObjectLayerRenderFrames;
-      const AtlasSpriteSheet = dbModels.AtlasSpriteSheet;
-      const File = dbModels.File;
-      const Ipfs = dbModels.Ipfs;
+      const CyberiaInstance = DataBaseProviderService.getModel('cyberia-instance', { host, path });
+      const CyberiaInstanceConf = DataBaseProviderService.getModel('cyberia-instance-conf', { host, path });
+      const CyberiaDialogue = DataBaseProviderService.getModel('cyberia-dialogue', { host, path });
+      const CyberiaMap = DataBaseProviderService.getModel('cyberia-map', { host, path });
+      const ObjectLayer = DataBaseProviderService.getModel('object-layer', { host, path });
+      const ObjectLayerRenderFrames = DataBaseProviderService.getModel('object-layer-render-frames', { host, path });
+      const AtlasSpriteSheet = DataBaseProviderService.getModel('atlas-sprite-sheet', { host, path });
+      const File = DataBaseProviderService.getModel('file', { host, path });
+      const Ipfs = DataBaseProviderService.getModel('ipfs', { host, path });
 
       const toBuffer = (value) => {
         if (!value) return null;
@@ -1911,7 +1909,7 @@ try {
         const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
         if (!instance) {
           logger.error(`CyberiaInstance with code "${instanceCode}" not found`);
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
           process.exit(1);
         }
 
@@ -1978,7 +1976,7 @@ try {
             backupDir,
             exportedFiles: ['cyberia-instance.json', 'cyberia-instance-conf.json'],
           });
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
           return;
         }
 
@@ -2293,7 +2291,7 @@ try {
             for (const failure of ipfsPayloadFailures) {
               logger.error('Canonical IPFS payload export failed', failure);
             }
-            await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+            await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
             process.exit(1);
           }
 
@@ -2372,7 +2370,7 @@ try {
 
         if (!fs.existsSync(backupDir)) {
           logger.error(`Backup directory not found: ${backupDir}`);
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
           process.exit(1);
         }
 
@@ -2594,7 +2592,7 @@ try {
             backupDir,
             importedFiles: ['cyberia-instance.json', 'cyberia-instance-conf.json'],
           });
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
           return;
         }
 
@@ -3211,7 +3209,106 @@ try {
         logger.error('Specify --export, --import, or --drop flag');
       }
 
-      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+    });
+
+  // ── client-hints: presentation hints management ──────────────────────────
+  program
+    .command('client-hints [instance-code]')
+    .option('--export [path]', 'Export CyberiaClientHints document to JSON (default: ./client-hints-<code>.json)')
+    .option('--import [path]', 'Upsert CyberiaClientHints from a JSON file')
+    .option('--seed-defaults', 'Upsert canonical presentation-hint defaults for the given instance code')
+    .option('--drop', 'Remove the CyberiaClientHints document for the given instance code')
+    .option('--env-path <env-path>', 'Env path e.g. ./engine-private/conf/dd-cyberia/.env.development')
+    .option('--mongo-host <mongo-host>', 'Mongo host override')
+    .option('--dev', 'Force development environment')
+    .description('Manage per-instance client presentation hints (palette, camera, status icons, interpolation)')
+    .action(async (instanceCode, options = {}) => {
+      try {
+        const envPath =
+          options.envPath || `./engine-private/conf/dd-cyberia/.env.${options.dev ? 'development' : 'production'}`;
+        if (fs.existsSync(envPath)) dotenv.config({ path: envPath, override: true });
+
+        const { CYBERIA_CLIENT_HINTS_DEFAULTS, buildClientHints } =
+          await import('../src/client/components/cyberia/SharedDefaultsCyberia.js');
+
+        const deployId = process.env.DEFAULT_DEPLOY_ID;
+        const host = process.env.DEFAULT_DEPLOY_HOST;
+        const path = process.env.DEFAULT_DEPLOY_PATH;
+        const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+        if (!fs.existsSync(confServerPath)) throw new Error(`Config not found: ${confServerPath}`);
+        const confServer = loadConfServerJson(confServerPath, { resolve: true });
+        const { db } = confServer[host][path];
+        db.host = options.mongoHost ? options.mongoHost : db.host.replace('127.0.0.1', 'mongodb-0.mongodb-service');
+
+        await DataBaseProviderService.load({ apis: ['cyberia-client-hints'], host, path, db });
+        const CyberiaClientHints = DataBaseProviderService.getModel('cyberia-client-hints', { host, path });
+
+        if (!instanceCode && !options.seedDefaults) {
+          logger.error('instance-code required for client-hints operations (omit only with --seed-defaults on all)');
+          process.exit(1);
+        }
+
+        if (options.drop) {
+          if (!instanceCode) {
+            logger.error('instance-code required for --drop');
+            process.exit(1);
+          }
+          const result = await CyberiaClientHints.deleteOne({ code: instanceCode });
+          logger.info(`client-hints --drop: removed ${result.deletedCount} document(s) for code="${instanceCode}"`);
+        }
+
+        if (options.seedDefaults) {
+          const codes = instanceCode ? [instanceCode] : [];
+          if (codes.length === 0) {
+            logger.error('instance-code required for --seed-defaults');
+            process.exit(1);
+          }
+          for (const code of codes) {
+            await CyberiaClientHints.findOneAndUpdate(
+              { code },
+              { $setOnInsert: { code, ...CYBERIA_CLIENT_HINTS_DEFAULTS } },
+              { upsert: true, returnDocument: 'after' },
+            );
+            logger.info(`client-hints --seed-defaults: seeded defaults for code="${code}"`);
+          }
+        }
+
+        if (options.import) {
+          const filePath = typeof options.import === 'string' ? options.import : `./client-hints-${instanceCode}.json`;
+          if (!fs.existsSync(filePath)) throw new Error(`Import file not found: ${filePath}`);
+          const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+          const code = data.code || instanceCode;
+          if (!code) {
+            logger.error('instance-code required (from file.code or CLI argument)');
+            process.exit(1);
+          }
+          await CyberiaClientHints.findOneAndUpdate({ code }, { $set: { code, ...data } }, { upsert: true, new: true });
+          logger.info(`client-hints --import: upserted code="${code}" from ${filePath}`);
+        }
+
+        if (options.export) {
+          if (!instanceCode) {
+            logger.error('instance-code required for --export');
+            process.exit(1);
+          }
+          const doc = await CyberiaClientHints.findOne({ code: instanceCode }).lean();
+          if (!doc) {
+            logger.warn(`No client-hints document found for code="${instanceCode}", exporting defaults`);
+          }
+          const outPath = typeof options.export === 'string' ? options.export : `./client-hints-${instanceCode}.json`;
+          fs.writeFileSync(
+            outPath,
+            JSON.stringify(doc || { code: instanceCode, ...CYBERIA_CLIENT_HINTS_DEFAULTS }, null, 2),
+          );
+          logger.info(`client-hints --export: wrote ${outPath}`);
+        }
+
+        await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
+      } catch (err) {
+        logger.error('client-hints command error:', err);
+        process.exit(1);
+      }
     });
 
   // ── chain: Hyperledger Besu / ERC-1155 lifecycle commands ────────────────
@@ -3411,7 +3508,7 @@ try {
           logger.info(`  SHA-256: ${resolved.sha256}`);
 
           // Close the DB connection after resolving
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
         } catch (dbErr) {
           logger.error(`Failed to resolve canonical CID from database: ${dbErr.message}`);
           process.exit(1);
@@ -3979,7 +4076,7 @@ try {
         }
 
         try {
-          await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+          await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
         } catch (_) {
           /* ignore close errors */
         }
@@ -4034,12 +4131,33 @@ try {
   runner
     .command('import-default-items')
     .option('--dev', 'Force development environment (loads .env.development for IPFS localhost, etc.)')
-    .description('Import default Object Layer items, skill config, and dialogues into MongoDB')
+    .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
+      // exist in DefaultCyberiaItems. Drift here causes silent missing
+      // sprites at runtime, so fail loudly before we touch MongoDB.
+      const { auditFallbackItemIds } = await import('../src/api/cyberia-instance/cyberia-fallback-world.js');
+      const missing = auditFallbackItemIds();
+      if (missing.length > 0) {
+        logger.error(
+          'import-default-items aborted: item ids referenced by defaults are missing from DefaultCyberiaItems:',
+          missing.join(', '),
+          '— add them to cyberia-server-defaults.js before seeding.',
+        );
+        process.exit(1);
+      }
+
       const devFlag = options.dev ? ' --dev' : '';
-      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}`);
+      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}${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
@@ -4079,10 +4197,10 @@ try {
 
       logger.info('seed-skill-config', { instanceCode, deployId, host, path, db });
 
-      await DataBaseProvider.load({ apis: ['cyberia-instance', 'cyberia-instance-conf'], host, path, db });
+      await DataBaseProviderService.load({ apis: ['cyberia-instance', 'cyberia-instance-conf'], host, path, db });
 
-      const CyberiaInstance = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaInstance;
-      const CyberiaInstanceConf = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaInstanceConf;
+      const CyberiaInstance = DataBaseProviderService.getModel('cyberia-instance', { host, path });
+      const CyberiaInstanceConf = DataBaseProviderService.getModel('cyberia-instance-conf', { host, path });
 
       const instance = await CyberiaInstance.findOne({ code: instanceCode }).lean();
 
@@ -4110,7 +4228,7 @@ try {
         DefaultSkillConfig.map((e) => `${e.triggerItemId} → [${e.logicEventIds.join(', ')}]`),
       );
 
-      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
     });
 
   runner
@@ -4148,9 +4266,9 @@ try {
 
       logger.info('seed-dialogues', { deployId, host, path, db });
 
-      await DataBaseProvider.load({ apis: ['cyberia-dialogue'], host, path, db });
+      await DataBaseProviderService.load({ apis: ['cyberia-dialogue'], host, path, db });
 
-      const CyberiaDialogue = DataBaseProvider.instance[`${host}${path}`].mongoose.models.CyberiaDialogue;
+      const CyberiaDialogue = DataBaseProviderService.getModel('cyberia-dialogue', { host, path });
 
       // Upsert each dialogue record keyed by (code, order) — idempotent.
       let upserted = 0;
@@ -4165,7 +4283,7 @@ try {
 
       logger.info(`seed-dialogues: ${upserted} dialogue records upserted`);
 
-      await DataBaseProvider.instance[`${host}${path}`].mongoose.close();
+      await DataBaseProviderService.getProvider({ host, path }, 'mongoose').close();
     });
 
   runner
@@ -4231,25 +4349,89 @@ try {
 
   runner
     .command('build-manifest')
-    .description('Build k8s resource manifest YAML files from templates')
-    .action(() => {
-      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' --kubeadm`);
-      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' --kind --dev`);
-      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' --kubeadm`);
-      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' --kind --dev`);
+    .option(
+      '--dev',
+      'Build dev-variant manifests (kind cluster, Dockerfile.dev). Default builds prod (kubeadm, Dockerfile).',
+    )
+    .description(
+      'Build k8s resource manifests for the Cyberia mmo-server + mmo-client instances. ' +
+        'Without --dev: production manifests (Dockerfile, kubeadm). With --dev: dev manifests (Dockerfile.dev, kind).',
+    )
+    .action((options) => {
+      const isDev = !!options.dev;
+      const flags = isDev ? '--kind --dev' : '--kubeadm';
+      // shellExec is fail-fast by default: any non-zero exit throws
+      // ShellExecError, which propagates to the outer catch and exits
+      // the CLI non-zero — observable by GitHub Actions.
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-client,./cyberia-client' ${flags}`);
+      shellExec(`node bin run instance-build-manifest 'dd-cyberia,mmo-server,./cyberia-server' ${flags}`);
+      // Copy canonical doc sources into the generated project READMEs.
+      // Edit the canonical sources; never hand-edit these generated outputs.
+      fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-CLIENT.md', './cyberia-client/README.md');
+      fs.copyFileSync('./src/client/public/cyberia-docs/CYBERIA-SERVER.md', './cyberia-server/README.md');
+      logger.info(`run-workflow build-manifest complete (${isDev ? 'dev' : 'prod'})`);
+    });
+
+  runner
+    .command('build-server-dashboard')
+    .option(
+      '--dev',
+      'Build a development variant of the dashboard with dev-specific env vars (e.g. localhost API endpoints).',
+    )
+    .option(
+      '--output-path <path>',
+      'Override output path for the rendered HTML (default: ./cyberia-server/public/index.html). ' +
+        'Used by CI when this command is invoked from inside an engine checkout that lives ' +
+        'alongside (not inside) the cyberia-server repo — pass e.g. ../public/index.html.',
+    )
+    .description('Build a static HTML dashboard for cyberia-server metrics and operational status. ')
+    .action((options) => {
+      const outputPath = options.outputPath || './cyberia-server/public/index.html';
+      shellExec(
+        `node bin static --page ./src/client/ssr/views/CyberiaServerMetrics.js` +
+          ` --output-path ${outputPath}` +
+          ` --title 'Cyberia Server Metrics'` +
+          ` --favicon /favicon.ico` +
+          ` --description 'Operational dashboard for the cyberia-server MMO runtime.'` +
+          ` --lang en` +
+          ` --env ${options.dev ? 'development' : 'production'}`,
+      );
     });
 
-  if (underpostProgram.commands.find((c) => c._name == process.argv[2]))
+  // Passthrough check: if the user invoked a command that is OWNED by the
+  // underpost CLI (not the cyberia overlay), throw the sentinel error so
+  // the catch block below can re-run argv through underpost. The match is
+  // strict on process.argv[2] (the first positional after `node bin/cyberia`)
+  // so we only passthrough when the top-level command name actually
+  // belongs to underpost.
+  if (
+    process.argv[2] &&
+    underpostProgram.commands.find((c) => c._name === process.argv[2]) &&
+    !program.commands.find((c) => c._name === process.argv[2])
+  ) {
     throw new Error('Trigger underpost passthrough');
+  }
 
-  program.parse();
+  await program.parseAsync();
 } catch (error) {
-  logger.warn(error);
-  process.argv = process.argv.filter((c) => c !== 'underpost');
-  logger.warn('Rerouting to underpost cli...');
-  try {
-    underpostProgram.parse();
-  } catch (error) {
+  // ONLY reroute on the explicit passthrough sentinel. Any other thrown
+  // error (subprocess non-zero from shellExec's fail-fast default, CLI
+  // parse errors, missing modules) must propagate as a non-zero process
+  // exit so GitHub Actions / CI parents observe the failure. Without this
+  // guard, a genuine build failure was being silently rerouted into the
+  // underpost CLI and then masked behind a misleading "unknown command"
+  // line.
+  if (error && error.message === 'Trigger underpost passthrough') {
+    process.argv = process.argv.filter((c) => c !== 'underpost');
+    logger.warn('Rerouting to underpost cli...');
+    try {
+      await underpostProgram.parseAsync();
+    } catch (err) {
+      logger.error(err);
+      process.exit(1);
+    }
+  } else {
     logger.error(error);
+    process.exit(1);
   }
 }

package/bump.config.js

@@ -0,0 +1,26 @@
+/**
+ * bumpp configuration for the Underpost engine.
+ *
+ * Owns the *canonical* version-bearing files (anything that exposes a literal `version` field
+ * bumpp can detect natively). Non-canonical files — image tags in workflows, README badges,
+ * doc strings, deployment.yaml image refs — are handled by the custom regex walker in
+ * src/cli/release.js (VERSION_BUMP_TARGETS), because bumpp only rewrites `version`-shaped lines.
+ *
+ * release.js drives bumpp programmatically (versionBump from 'bumpp') with commit/tag/push
+ * disabled, since the engine release flow stages and commits separately via `node bin cmt`.
+ *
+ * @see https://github.com/antfu/bumpp
+ */
+export default {
+  files: [
+    'package.json',
+    'package-lock.json',
+    // engine-private confs are git-ignored and visited only if present at bump time.
+    'engine-private/conf/**/package.json',
+  ],
+  commit: false,
+  tag: false,
+  push: false,
+  confirm: false,
+  recursive: false,
+};