cyberia 3.2.22 → 3.2.70

package/scripts/rpmfusion-ffmpeg-setup.sh

@@ -1,56 +1,32 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Purpose: enable required repos (CRB, EPEL, RPM Fusion) and attempt to install ffmpeg on Rocky/Alma/RHEL-9 compatible systems.
+echo "1) Ensure dnf-plugins-core is installed"
+dnf -y install dnf-plugins-core
 
-if [ "${EUID:-$(id -u)}" -ne 0 ]; then
-  echo "This script must be run as root or with sudo. Exiting."
-  exit 1
-fi
+echo "2) Enable CRB"
+dnf config-manager --set-enabled crb || true
 
-echo "1) Ensure dnf-plugins-core is available (for config-manager)"
-dnf -y install dnf-plugins-core
+echo "3) Install EPEL"
+dnf -y install epel-release \
+|| dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
+
+echo "4) Install RPM Fusion repositories"
+dnf -y install \
+https://download1.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
+https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm
+
+
+echo "5) Install libwebp-tools (for ffmpeg to support WebP)"
+dnf -y install libwebp-tools
+
+echo "6) Refresh metadata"
+dnf clean all
+dnf makecache --refresh
+
+echo "7) Install ffmpeg"
+dnf -y install ffmpeg ffmpeg-devel --allowerasing
 
-echo "2) Enable CodeReady / CRB (needed for some deps, e.g. ladspa)"
-# On RHEL you'd use subscription-manager; on CentOS/Rocky/Alma use config-manager
-dnf config-manager --set-enabled crb
-
-echo "3) Install EPEL release (required by some ffmpeg deps)"
-dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
-
-echo "4) Add RPM Fusion (free + nonfree) repositories"
-# Using mirrors.rpmfusion.org recommended links
-dnf -y install https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
-               https://mirrors.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm
-
-echo "5) Refresh metadata and update system"
-dnf -y makecache
-# Optional: update system packages (comment out if you don't want a full update)
-# dnf -y update
-
-echo "6) Try to install audio helper packages that sometimes block ffmpeg (ladspa, rubberband)"
-# These may be provided by CRB/EPEL or other compatible repos
-dnf -y install ladspa || echo "ladspa not available from enabled repos (will try later)"
-dnf -y install rubberband || echo "rubberband not available from enabled repos (will try later)"
-dnf -y install libwebp-tools || echo "libwebp-tools not available from enabled repos (will try later)"
-
-echo "7) Try installing ffmpeg (several fallbacks tried)"
-if dnf -y install ffmpeg ffmpeg-devel --allowerasing; then
-  echo "ffmpeg installed successfully (used --allowerasing)."
-elif dnf -y install ffmpeg ffmpeg-devel --nobest; then
-  echo "ffmpeg installed successfully (used --nobest)."
-elif dnf -y install ffmpeg ffmpeg-devel --skip-broken; then
-  echo "ffmpeg installed (skip-broken). Some optional packages may have been skipped."
-else
-  echo "Automatic install failed."
-  echo "Helpful troubleshooting steps:"
-  echo " - Check which repo provides ladspa: dnf repoquery --whatprovides 'ladspa'"
-  echo " - Check which package provides librubberband: dnf repoquery --whatprovides 'librubberband.so.2'"
-  echo " - Try enabling CRB and EPEL (we already attempted that). If ladspa/rubberband are still missing you can fetch their EL9 rpm from a trusted mirror or build them."
-  echo " - Example manual install (ONLY if you trust the source): sudo dnf install /path/to/ladspa-*.el9.rpm /path/to/rubberband-*.el9.rpm"
-  echo " - After satisfying ladspa/rubberband, rerun: sudo dnf install ffmpeg ffmpeg-devel"
-  exit 2
-fi
-
-echo "\nInstallation finished. Verify with: ffmpeg -version"
-exit 0
+echo
+echo "Done."
+ffmpeg -version | head -n 1

package/scripts/test-monitor.sh

@@ -2,9 +2,7 @@
 #
 # test-monitor.sh — end-to-end deploy + two-phase monitor smoke test.
 #
-# Two deployment shapes are supported (see
-# src/client/public/nexodev/docs/references/Deploy-Monitor-PRD.md and
-# 'Deploy custom instance to K8S.md'):
+# Two deployment shapes are supported:
 #
 #   --mode runtime   `underpost start` deploy (e.g. dd-test). Monitored with the
 #                    HTTP gate: /_internal/ready probes + port-forward status.
@@ -26,11 +24,11 @@ MODE=runtime                                  # runtime | instance
 ENV=development                               # development | production
 DEPLOY_ID=dd-test                             # deploy id (instance mode: parent of conf.instances.json)
 INSTANCE_IDS=                                 # instance mode: csv of ids (default: all in conf.instances.json)
-IMAGE=underpost/wp:v3.2.14                    # runtime mode image (instance mode reads image from conf)
+IMAGE=underpost/wp:v3.2.70                    # runtime mode image (instance mode reads image from conf)
 VERSIONS=green                                # csv of blue/green versions
 REPLICAS=1                                    # replicas per deployment
 NAMESPACE=default                             # k8s namespace
-CLUSTER=                                      # kind | kubeadm | k3s | "" (auto/none)
+CLUSTER=kind                                  # kind | kubeadm | k3s | "" (auto/none)
 TIMEOUT_RESPONSE=300000ms                     # HTTPProxy per-route response timeout
 TEMPLATE_REPO=underpostnet/pwa-microservices-template-private  # runtime mode link repo
 ENVOY_NAMESPACE=projectcontour                # ingress namespace (instance TLS exposure)

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.router.js

@@ -1,6 +1,7 @@
 import { loggerFactory } from '../../server/logger.js';
 import { AtlasSpriteSheetController } from './atlas-sprite-sheet.controller.js';
 import express from 'express';
+import { moderatorGuard, adminGuard } from '../../server/auth.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -14,19 +15,34 @@ class AtlasSpriteSheetRouter {
     router.post(
       `/generate/:id`,
       options.authMiddleware,
+      moderatorGuard,
       async (req, res) => await AtlasSpriteSheetController.generate(req, res, options),
     );
     router.delete(
       `/object-layer/:id`,
       options.authMiddleware,
+      moderatorGuard,
       async (req, res) => await AtlasSpriteSheetController.deleteByObjectLayerId(req, res, options),
     );
-    router.post(`/:id`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.post(req, res, options));
-    router.post(`/`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.post(req, res, options));
+    router.post(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.post(req, res, options),
+    );
+    router.post(
+      `/`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.post(req, res, options),
+    );
     router.get(`/blob/:itemKey`, async (req, res) => await AtlasSpriteSheetController.blob(req, res, options));
     // Metadata endpoints: returns itemKey, atlasWidth, atlasHeight, cellPixelDim, frames (no fileId).
     // Client fetches /metadata/:itemKey once, caches it, then fetches /blob/:itemKey for the PNG.
-    router.get(`/metadata/:itemKey`, async (req, res) => await AtlasSpriteSheetController.getMetadata(req, res, options));
+    router.get(
+      `/metadata/:itemKey`,
+      async (req, res) => await AtlasSpriteSheetController.getMetadata(req, res, options),
+    );
     router.get(`/metadata`, async (req, res) => await AtlasSpriteSheetController.getMetadata(req, res, options));
     router.get(
       `/:id`,
@@ -34,10 +50,30 @@ class AtlasSpriteSheetRouter {
       async (req, res) => await AtlasSpriteSheetController.get(req, res, options),
     );
     router.get(`/`, async (req, res) => await AtlasSpriteSheetController.get(req, res, options));
-    router.put(`/:id`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.put(req, res, options));
-    router.put(`/`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.put(req, res, options));
-    router.delete(`/:id`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.delete(req, res, options));
-    router.delete(`/`, options.authMiddleware, async (req, res) => await AtlasSpriteSheetController.delete(req, res, options));
+    router.put(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.put(req, res, options),
+    );
+    router.put(
+      `/`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.put(req, res, options),
+    );
+    router.delete(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await AtlasSpriteSheetController.delete(req, res, options),
+    );
+    router.delete(
+      `/`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await AtlasSpriteSheetController.delete(req, res, options),
+    );
     return router;
   }
 }

package/src/api/atlas-sprite-sheet/atlas-sprite-sheet.service.js

@@ -1,10 +1,10 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
-import { AtlasSpriteSheetGenerator } from '../../server/atlas-sprite-sheet-generator.js';
+import { AtlasSpriteSheetGenerator } from '../../projects/cyberia/atlas-sprite-sheet-generator.js';
 import { FileFactory } from '../file/file.service.js';
 import { AtlasSpriteSheetDto } from './atlas-sprite-sheet.model.js';
-import { IpfsClient } from '../../server/ipfs-client.js';
+import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
 import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
 
 const logger = loggerFactory(import.meta);
@@ -54,10 +54,9 @@ async function withResolvedAtlasFrameDuration(doc, ObjectLayer) {
 class AtlasSpriteSheetService {
   static blob = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel("File", options);
+    const File = DataBaseProviderService.getModel('File', options);
 
     const itemKey = req.params.itemKey;
     const atlasDoc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': itemKey }).lean();
@@ -70,12 +69,11 @@ class AtlasSpriteSheetService {
   };
   static generate = async (req, res, options, generateOptions = {}) => {
     /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel("File", options);
+    const File = DataBaseProviderService.getModel('File', options);
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
 
     let objectLayer = req.objectLayer;
 
@@ -195,12 +193,11 @@ class AtlasSpriteSheetService {
   };
   static deleteByObjectLayerId = async (req, res, options) => {
     /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel("File", options);
+    const File = DataBaseProviderService.getModel('File', options);
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
 
     const objectLayer = await ObjectLayer.findById(req.params.id);
     if (!objectLayer) {
@@ -254,14 +251,12 @@ class AtlasSpriteSheetService {
   };
   static post = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     return await new AtlasSpriteSheet(req.body).save();
   };
   static get = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     if (req.params.id)
       return await AtlasSpriteSheet.findById(req.params.id)
         .select(AtlasSpriteSheetDto.select.get())
@@ -287,10 +282,9 @@ class AtlasSpriteSheetService {
   // Client fetches this once per itemKey, caches it, then fetches the PNG blob.
   static getMetadata = async (req, res, options) => {
     /** @type {import('../object-layer/object-layer.model.js').ObjectLayerModel} */
-    const ObjectLayer = DataBaseProviderService.getModel("ObjectLayer", options);
+    const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
 
     if (req.params.itemKey) {
       const doc = await AtlasSpriteSheet.findOne({ 'metadata.itemKey': req.params.itemKey })
@@ -328,16 +322,14 @@ class AtlasSpriteSheetService {
   };
   static put = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     return await AtlasSpriteSheet.findByIdAndUpdate(req.params.id, req.body);
   };
   static delete = async (req, res, options) => {
     /** @type {import('./atlas-sprite-sheet.model.js').AtlasSpriteSheetModel} */
-    const AtlasSpriteSheet =
-      DataBaseProviderService.getModel("AtlasSpriteSheet", options);
+    const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
     /** @type {import('../file/file.model.js').FileModel} */
-    const File = DataBaseProviderService.getModel("File", options);
+    const File = DataBaseProviderService.getModel('File', options);
 
     if (req.params.id) {
       const atlasDoc = await AtlasSpriteSheet.findById(req.params.id);

package/src/api/cyberia-action/cyberia-action.controller.js

@@ -39,6 +39,25 @@ class CyberiaActionController {
       });
     }
   };
+  static getByCode = async (req, res, options) => {
+    try {
+      if (req && req.headers && req.headers.origin) {
+        res.set('Access-Control-Allow-Origin', req.headers.origin);
+      } else res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+      const result = await CyberiaActionService.getByCode(req, res, options);
+      return res.status(200).json({
+        status: 'success',
+        data: result,
+      });
+    } catch (error) {
+      logger.error(error, error.stack);
+      return res.status(404).json({
+        status: 'error',
+        message: error.message,
+      });
+    }
+  };
   static put = async (req, res, options) => {
     try {
       const result = await CyberiaActionService.put(req, res, options);

package/src/api/cyberia-action/cyberia-action.model.js

@@ -1,48 +1,42 @@
 import { Schema, model } from 'mongoose';
-import { CYBERIA_ACTION_TYPES } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 
 // https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
 
 const CyberiaActionSchema = new Schema(
   {
-    // Spatial origin: the NPC/entity cell that provides this action.
-    // Matched against map entity initCellX/initCellY during instance init
-    // and assignable from ObjectLayerEngineModal.
+    // Spatial origin: the cell whose matching bot entity provides this action.
+    // An action has NO type — its capabilities are whatever payloads are
+    // populated (questDialogueCodes / shopItems / craftRecipes / storageSlots),
+    // resolved per player. The quest-provider capability is active when there
+    // are CyberiaQuests bound to this same (sourceMapCode, sourceCellX,
+    // sourceCellY).
     sourceMapCode: { type: String, trim: true },
     sourceCellX: { type: Number },
     sourceCellY: { type: Number },
 
     // ── Identity ──────────────────────────────────────────────────────────
+    // `code` is a generic, location-scoped slug (it associates the action with
+    // its cell, not a single behavior). `label` is the name shown on the bot's
+    // overhead nameplate (the client fetches it by code via REST).
     code: { type: String, required: true, trim: true },
-    type: {
-      type: String,
-      required: true,
-      trim: true,
-      enum: CYBERIA_ACTION_TYPES,
-    },
     label: { type: String, trim: true, default: '' },
 
-    // The item ID of the NPC/entity that provides this action.
-    // Used to match 'talk' quest objectives: a step with { type: 'talk', itemId: X }
-    // is satisfied when the player triggers an action where provideItemId === X.
-    // Typically the entity's active skin ObjectLayer item ID (e.g. 'wason', 'alex').
-    provideItemId: { type: String, trim: true, default: '' },
-
-    // Quest code granted to the player on their first interaction with this action.
-    // Used by 'quest-talk' NPCs to start a quest chain on first contact.
-    // Empty string = no quest granted.
-    grantQuestCode: { type: String, trim: true, default: '' },
-
     // ── Dialogue ──────────────────────────────────────────────────────────
-    // General greeting/intro dialogue shown when the action button is tapped.
+    // General greeting shown when the interaction modal opens. Empty = client
+    // falls back to /code/default-<skin> from the entity's active skin.
     dialogCode: { type: String, trim: true, default: '' },
 
-    // Ordered list of CyberiaDialogue codes the player must view to satisfy
-    // a 'talk' quest objective linked to this action via provideItemId.
-    // For simple actions this may match dialogCode; for multi-stage NPCs it can diverge.
-    questDialogueCodes: [{ type: String, trim: true }],
+    // Per-quest dialogue map: the CyberiaDialogue code to display for each quest
+    // this NPC handles. The server validates a `talk` objective only when the
+    // viewed dialogCode matches the entry for that quest.
+    questDialogueCodes: [
+      {
+        questCode: { type: String, required: true, trim: true },
+        dialogCode: { type: String, required: true, trim: true },
+      },
+    ],
 
-    // ── Shop payload (type="shop") ─────────────────────────────────────────
+    // ── Shop payload ──────────────────────────────────────────────────────
     shopItems: [
       {
         itemId: { type: String, required: true, trim: true },
@@ -76,8 +70,6 @@ const CyberiaActionSchema = new Schema(
 );
 
 CyberiaActionSchema.index({ code: 1 }, { unique: true });
-CyberiaActionSchema.index({ provideItemId: 1 });
-CyberiaActionSchema.index({ grantQuestCode: 1 }, { sparse: true });
 CyberiaActionSchema.index({ sourceMapCode: 1, sourceCellX: 1, sourceCellY: 1 });
 
 const CyberiaActionModel = model('CyberiaAction', CyberiaActionSchema);

package/src/api/cyberia-action/cyberia-action.router.js

@@ -1,6 +1,7 @@
 import { loggerFactory } from '../../server/logger.js';
 import { CyberiaActionController } from './cyberia-action.controller.js';
 import express from 'express';
+import { moderatorGuard, adminGuard } from '../../server/auth.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -11,17 +12,51 @@ class CyberiaActionRouter {
    */
   static router(options) {
     const router = express.Router();
-    router.post(`/:id`, async (req, res) => await CyberiaActionController.post(req, res, options));
-    router.post(`/`, async (req, res) => await CyberiaActionController.post(req, res, options));
-    router.get(`/:id`,
+    router.post(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaActionController.post(req, res, options),
+    );
+    router.post(
+      `/`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaActionController.post(req, res, options),
+    );
+    // Direct lookup by code — the client fetches an NPC's action metadata
+    // (label, dialogue map) by the action code the Go server sends over AOI.
+    router.get(`/code/:code`, async (req, res) => await CyberiaActionController.getByCode(req, res, options));
+    router.get(
+      `/:id`,
       // options.authMiddleware,
       async (req, res) => await CyberiaActionController.get(req, res, options),
     );
     router.get(`/`, async (req, res) => await CyberiaActionController.get(req, res, options));
-    router.put(`/:id`, async (req, res) => await CyberiaActionController.put(req, res, options));
-    router.put(`/`, async (req, res) => await CyberiaActionController.put(req, res, options));
-    router.delete(`/:id`, async (req, res) => await CyberiaActionController.delete(req, res, options));
-    router.delete(`/`, async (req, res) => await CyberiaActionController.delete(req, res, options));
+    router.put(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaActionController.put(req, res, options),
+    );
+    router.put(
+      `/`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaActionController.put(req, res, options),
+    );
+    router.delete(
+      `/:id`,
+      options.authMiddleware,
+      moderatorGuard,
+      async (req, res) => await CyberiaActionController.delete(req, res, options),
+    );
+    router.delete(
+      `/`,
+      options.authMiddleware,
+      adminGuard,
+      async (req, res) => await CyberiaActionController.delete(req, res, options),
+    );
     return router;
   }
 }

package/src/api/cyberia-action/cyberia-action.service.js

@@ -1,18 +1,19 @@
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
 import { loggerFactory } from '../../server/logger.js';
 import { DataQuery } from '../../server/data-query.js';
+import { DefaultCyberiaActions } from '../cyberia-server-defaults/cyberia-server-defaults.js';
 
 const logger = loggerFactory(import.meta);
 
 class CyberiaActionService {
   static post = async (req, res, options) => {
     /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
-    const CyberiaAction = DataBaseProviderService.getModel("CyberiaAction", options);
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
     return await new CyberiaAction(req.body).save();
   };
   static get = async (req, res, options) => {
     /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
-    const CyberiaAction = DataBaseProviderService.getModel("CyberiaAction", options);
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
     if (req.params.id) return await CyberiaAction.findById(req.params.id);
 
     // Parse query parameters using DataQuery helper
@@ -26,14 +27,29 @@ class CyberiaActionService {
     const totalPages = Math.ceil(total / limit);
     return { data, total, page, totalPages };
   };
+  static getByCode = async (req, res, options) => {
+    /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
+    const { code } = req.params;
+    if (!code) throw new Error('code parameter is required');
+    const data = await CyberiaAction.findOne({ code }).lean();
+    if (data) return data;
+    // Fallback world delivers actions to the Go server from the canonical
+    // defaults without persisting them; serve those so the client can fetch the
+    // action's label + dialogue map by code. Quest OFFERS are NOT resolved here —
+    // the client locates offered quests via the cyberia-quest API by cell.
+    const fallback = DefaultCyberiaActions.find((a) => a.code === code);
+    if (fallback) return fallback;
+    throw new Error(`No action found for code: ${code}`);
+  };
   static put = async (req, res, options) => {
     /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
-    const CyberiaAction = DataBaseProviderService.getModel("CyberiaAction", options);
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
     return await CyberiaAction.findByIdAndUpdate(req.params.id, req.body);
   };
   static delete = async (req, res, options) => {
     /** @type {import('./cyberia-action.model.js').CyberiaActionModel} */
-    const CyberiaAction = DataBaseProviderService.getModel("CyberiaAction", options);
+    const CyberiaAction = DataBaseProviderService.getModel('CyberiaAction', options);
     if (req.params.id) return await CyberiaAction.findByIdAndDelete(req.params.id);
     else return await CyberiaAction.deleteMany();
   };