@underpostnet/cyberia 3.2.80

package/README.md

@@ -0,0 +1,259 @@
+<div align="center">
+
+  <img src="https://www.cyberiaonline.com/assets/splash/apple-touch-icon-precomposed.png" alt="CYBERIA Network Object Layer Engine"/>
+
+<h1>CYBERIA</h1>
+
+**Network Object Layers**
+
+_Stackable Rendering Layers as a Unified Tokenized Reality_
+
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
+
+</div>
+Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
+toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
+runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.
+
+`engine-cyberia` is the **sidecar-backed data layer**: a Node.js sidecar that owns content,
+validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
+Go server and the WASM client with data — it does not run the simulation or the presentation.
+
+---
+
+## Ecosystem at a glance
+
+```text
+                         ┌───────────────────────────────────────────────┐
+                         │              UNDERPOST PLATFORM                 │
+                         │  toolchain · deploy · PWA build · static        │
+                         │  delivery · cluster/image/db · monitoring       │
+                         │                                                 │
+                         │   underpost CLI  ──▶  builds & deploys all      │
+                         └───────────────────────────────────────────────┘
+                                            │  hosts / delivers
+                                            ▼
+   ╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
+   ║                                                                               ║
+   ║   ┌──────────────────┐   gRPC    ┌──────────────────┐   WebSocket            ║
+   ║   │  engine-cyberia  │ ────────▶ │  cyberia-server  │ ───────────┐           ║
+   ║   │     (Node.js)    │           │       (Go)       │            │           ║
+   ║   │                  │           │                  │            ▼           ║
+   ║   │ content          │           │ authoritative    │   ┌──────────────────┐ ║
+   ║   │ validation       │           │ simulation       │   │  cyberia-client  │ ║
+   ║   │ persistence      │           │ world tick       │   │    (C / WASM)    │ ║
+   ║   │ gRPC/REST data   │           │ AOI replication  │   │                  │ ║
+   ║   │ asset metadata   │           │                  │   │ rendering        │ ║
+   ║   └──────────────────┘           └──────────────────┘   │ input            │ ║
+   ║            │                                             │ prediction       │ ║
+   ║            └──────────────── REST (content/assets) ─────▶│ presentation     │ ║
+   ║                                                          └──────────────────┘ ║
+   ╚═══════════════════════════════════════════════════════════════════════════════╝
+
+   One source of truth per concern:
+     content & world config ── engine-cyberia
+     real-time world state  ── cyberia-server
+     presentation & input   ── cyberia-client
+```
+
+---
+
+## 1. Toolchain and base infrastructure
+
+Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
+selection, host/path layout, generated client assets, and environment resolution.
+
+| Area            | What it owns                                                                         |
+| --------------- | ------------------------------------------------------------------------------------ |
+| Toolchain       | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection    |
+| Infrastructure  | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners                      |
+| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring                             |
+| Delivery        | static build, SSR views, PWA packaging, service worker generation, host/path routing |
+
+`underpost` is the shared control surface for everything infrastructural. Cyberia-specific work belongs
+in the `cyberia` CLI, never in parallel platform commands. When a concern already exists in `underpost`,
+reuse it instead of forking a Cyberia variant.
+
+---
+
+## 2. PWA workflow
+
+Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
+inputs:
+
+- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
+- the service worker source in `src/client/sw/core.sw.js`
+
+Everything else — `index.html` pages, `sw.js`, the precache list — is **generated** during the client
+build. Treat them as outputs only; never hand-edit them.
+
+Runtime service-worker behavior:
+
+| Request       | Strategy                         |
+| ------------- | -------------------------------- |
+| static assets | stale-while-revalidate           |
+| API `GET`     | network-first + short cache      |
+| API mutations | network-only + background replay |
+| navigation    | network-first + fallback shells  |
+
+Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
+fallback view. Only fallback-marked views are guaranteed precached.
+
+---
+
+## 3. Cyberia MMO extension
+
+### Responsibility split
+
+| Service          | Owns                                                                      | Must not own                                  |
+| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
+| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy       |
+| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication  | content authority, presentation metadata      |
+| `cyberia-client` | rendering, input, prediction, interpolation, presentation                 | authoritative world state, gameplay authority |
+
+Two boundaries are non-negotiable:
+
+- Do not move authoritative logic into the client.
+- Do not move content-authority logic into the Go runtime.
+
+### Data flow
+
+```text
+engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
+engine-cyberia ──REST──────────────────────────────▶ cyberia-client
+```
+
+### `engine-cyberia` as the sidecar-backed data layer
+
+`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
+
+- Boot-time world configuration flows from `engine-cyberia` to `cyberia-server` over gRPC `GetFullInstance`.
+- Client-facing assets, object layers, dialogues, and presentation hints flow from `engine-cyberia` to `cyberia-client` over REST.
+- Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.
+
+### Runtime / health model
+
+Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.
+
+```text
+        ┌──────────────────────────────────────────────────────────────┐
+        │                    SUPERVISION (parallel)                      │
+        │                                                                │
+        │   engine-cyberia        cyberia-server        cyberia-client   │
+        │   ┌────────────┐        ┌────────────┐        ┌────────────┐   │
+        │   │  monitor   │        │  monitor   │        │  monitor   │   │
+        │   │ +reconnect │        │ +reconnect │        │ +reconnect │   │
+        │   └─────┬──────┘        └─────┬──────┘        └─────┬──────┘   │
+        │         │                     │                     │          │
+        │         └──────────┬──────────┴──────────┬──────────┘          │
+        │                    ▼                     ▼                     │
+        │            all three up & connected?                          │
+        └────────────────────────────┬─────────────────────────────────┘
+                                      │
+                ┌─────────────────────┼─────────────────────┐
+                ▼                     ▼                     ▼
+          ┌───────────┐        ┌───────────┐         ┌───────────┐
+          │  HEALTHY  │        │ DEGRADED  │         │  STANDBY  │
+          │ all 3 up  │        │ ≥1 service│         │ gameplay  │
+          │ gameplay  │        │ reconnect-│         │ paused    │
+          │ live      │        │ ing / down│         │ until all │
+          │           │        │           │         │ 3 healthy │
+          └───────────┘        └───────────┘         └───────────┘
+```
+
+| State      | Meaning                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `healthy`  | all three Cyberia services are up and connected                      |
+| `degraded` | at least one service is reconnecting or unavailable                  |
+| `standby`  | gameplay is paused because the full three-service set is not healthy |
+
+---
+
+## User commands
+
+Use `underpost` for platform, infrastructure, build, and deploy. Use `cyberia` for MMO content and
+extension workflows. Both share the same helpers — never duplicate config, env, or path logic.
+
+### Platform (underpost)
+
+```bash
+# Bootstrap a new app (local app serves on http://localhost:4001)
+underpost new app-name
+
+# Build the client bundle / static + PWA output
+underpost client
+npm run build            # node bin client
+
+# Deploy and operate
+underpost deploy <deploy-id>
+underpost monitor
+```
+
+### Cyberia (cyberia) — `bin/cyberia.js`
+
+| Group          | Command                                | Purpose                                                  |
+| -------------- | -------------------------------------- | -------------------------------------------------------- |
+| `ol`           | `cyberia ol [item-id]`                 | ObjectLayer import, procedural generation, atlas/sprite  |
+| `instance`     | `cyberia instance [instance-code]`     | export / import / drop a Cyberia instance and its data   |
+| `client-hints` | `cyberia client-hints [instance-code]` | per-instance presentation hints (palette, camera, icons) |
+| `chain`        | `cyberia chain <sub>`                  | Hyperledger Besu + ERC-1155 ObjectLayerToken lifecycle   |
+| `run-workflow` | `cyberia run-workflow <name>`          | named maintenance/build scripts from `scripts/`          |
+
+Common examples:
+
+```bash
+# Object layer content
+cyberia ol hatchet,sword --import                 # import specific items
+cyberia ol --import-types skin,floors             # batch import by type (or: all)
+cyberia ol floor-desert --generate --seed fx-42   # procedural generation
+cyberia ol hatchet --to-atlas-sprite-sheet        # build atlas sprite sheet
+cyberia ol --drop --client-public                 # drop data + static asset folders
+
+# Instance data
+cyberia instance FOREST --export ./backup
+cyberia instance FOREST --import ./backup
+cyberia instance FOREST --drop
+
+# Presentation hints
+cyberia client-hints cyberia-main --seed-defaults
+
+# Chain / token lifecycle
+cyberia chain deploy --chain-id 777771
+cyberia chain status
+cyberia chain register / mint / transfer / burn / pause / unpause
+
+# Named workflows
+cyberia run-workflow import-default-items
+cyberia run-workflow seed-skills
+cyberia run-workflow seed-dialogues
+cyberia run-workflow build-manifest
+cyberia run-workflow build-server-dashboard
+```
+
+### Run the MMO services
+
+```bash
+# engine-cyberia (Node.js data/content services)
+npm start                                          # node src/server
+
+# cyberia-server (Go authoritative simulation)
+cd cyberia-server && go run main.go                # dev
+cd cyberia-server && go build -o cyberia-server . && ./cyberia-server
+
+# cyberia-client (C / WASM presentation)
+cd cyberia-client && make -f Web.mk clean && make -f Web.mk web
+cd cyberia-client && make -f Web.mk serve-development     # serves on :8082
+```
+
+---
+
+## Operational guardrails
+
+- Prefer one source of truth for config, deploy IDs, runtime selection, startup behavior, and generated assets.
+- Reuse existing helpers and conventions instead of creating parallel implementations.
+- Do not duplicate parsing, env resolution, or path normalization logic across modules.
+- Treat generated artifacts (`sw.js`, static pages, atlases, README, manifests) as outputs only.
+- Host-level changes must be idempotent, reversible, and explicit; validate before mutating; keep
+  orchestration scripts safe to rerun.
+- `engine-private/` is a private external dependency. Reference it only as private input; never assume
+  its contents exist locally.

package/baremetal/commission-workflows.json

@@ -0,0 +1,211 @@
+{
+  "rpi4mbarm64-iso-ram": {
+    "type": "iso-ram",
+    "osIdLike": "debian ubuntu",
+    "architecture": "arm64",
+    "isoUrl": "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 ISO-RAM Ubuntu 24.04 ephemeral commissioning (ARM64)",
+    "networkInterfaceName": "enabcm6e4ei0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "maas": {
+      "commissioning": {
+        "architecture": "arm64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-chroot": {
+    "type": "chroot-debootstrap",
+    "osIdLike": "debian ubuntu",
+    "architecture": "arm64",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 CHROOT Ubuntu 24.04 ephemeral commissioning (ARM64)",
+    "networkInterfaceName": "enabcm6e4ei0",
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "debootstrap": {
+      "image": {
+        "architecture": "arm64",
+        "name": "noble"
+      }
+    },
+    "maas": {
+      "commissioning": {
+        "architecture": "arm64/ga-24.04",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-iso-nfs": {
+    "type": "iso-nfs",
+    "osIdLike": "debian ubuntu",
+    "architecture": "arm64",
+    "isoUrl": "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/GRUB/MAAS RPi4 ISO-NFS Ubuntu 24.04 ephemeral commissioning (ARM64)",
+    "networkInterfaceName": "enabcm6e4ei0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "maas": {
+      "commissioning": {
+        "architecture": "arm64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "rpi4mbarm64-chroot-rocky9": {
+    "type": "chroot-container",
+    "osIdLike": "rhel centos fedora",
+    "architecture": "arm64",
+    "tftpPrefix": "rpi4mb",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET Container CHROOT Rocky Linux 9 ephemeral commissioning (ARM64)",
+    "networkInterfaceName": "eth0",
+    "firmwares": [
+      {
+        "url": "https://github.com/pftf/RPi4/releases/download/v1.41/RPi4_UEFI_Firmware_v1.41.zip",
+        "gateway": "192.168.1.1",
+        "subnet": "255.255.255.0"
+      }
+    ],
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "container": {
+      "image": "quay.io/rockylinux/rockylinux:9",
+      "architecture": "arm64",
+      "packages": ["kernel", "chrony", "kbd", "glibc-langpack-en", "glibc-langpack-es", "tzdata"]
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "hp-envy-iso-nfs": {
+    "type": "iso-nfs",
+    "osIdLike": "debian ubuntu",
+    "architecture": "amd64",
+    "isoUrl": "https://releases.ubuntu.com/releases/24.04/ubuntu-24.04.3-live-server-amd64.iso",
+    "tftpPrefix": "envy",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/ISO-IPXE/MAAS hp-envy ISO-NFS Ubuntu 24.04 ephemeral commissioning (AMD64)",
+    "networkInterfaceName": "eth0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [],
+    "maas": {
+      "commissioning": {
+        "architecture": "amd64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "hp-envy-iso-ram": {
+    "type": "iso-ram",
+    "osIdLike": "debian ubuntu",
+    "architecture": "amd64",
+    "isoUrl": "https://releases.ubuntu.com/releases/24.04/ubuntu-24.04.3-live-server-amd64.iso",
+    "tftpPrefix": "envy",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/ISO-IPXE/MAAS hp-envy ISO-RAM Ubuntu 24.04 ephemeral commissioning (AMD64)",
+    "networkInterfaceName": "eth0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [],
+    "maas": {
+      "commissioning": {
+        "architecture": "amd64/hwe-24.04-edge",
+        "name": "ubuntu/noble"
+      }
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  },
+  "hp-envy-iso-ram-rocky9": {
+    "type": "iso-ram",
+    "osIdLike": "rhel centos fedora",
+    "architecture": "amd64",
+    "infraSetup": "underpost-kubeadm-contour",
+    "isoUrl": "https://download.rockylinux.org/pub/rocky/9/isos/x86_64/Rocky-9-latest-x86_64-boot.iso",
+    "tftpPrefix": "envy-rocky9",
+    "bootstrapHttpServerPort": 8888,
+    "menuentryStr": "UNDERPOST.NET UEFI/ISO-IPXE/KICKSTART-ANACONDA hp-envy ISO-RAM Rocky Linux 9 ephemeral commissioning (AMD64)",
+    "networkInterfaceName": "eth0",
+    "chronyc": {
+      "timezone": "America/Santiago",
+      "chronyConfPath": "/etc/chrony/chrony.conf"
+    },
+    "firmwares": [],
+    "container": {
+      "image": "quay.io/rockylinux/rockylinux:9",
+      "architecture": "amd64",
+      "packages": [
+        "kernel",
+        "kernel-core",
+        "kernel-modules",
+        "linux-firmware",
+        "dracut",
+        "dracut-network",
+        "dracut-config-generic",
+        "dracut-live",
+        "nfs-utils",
+        "tar",
+        "iproute",
+        "openssh-server",
+        "openssh-clients"
+      ]
+    },
+    "keyboard": {
+      "layout": "es"
+    }
+  }
+}

package/baremetal/packer-workflows.json

@@ -0,0 +1,24 @@
+{
+  "Rocky9Amd64": {
+    "dir": "packer/images/Rocky9Amd64",
+    "maas": {
+      "name": "custom/rocky9",
+      "title": "Rocky 9 Custom",
+      "architecture": "amd64/generic",
+      "base_image": "rhel/9",
+      "filetype": "tgz",
+      "content": "rocky9.tar.gz"
+    }
+  },
+  "Rocky9Arm64": {
+    "dir": "packer/images/Rocky9Arm64",
+    "maas": {
+      "name": "custom/rocky9-arm64",
+      "title": "Rocky 9 Arm64 Custom",
+      "architecture": "arm64/generic",
+      "base_image": "rhel/9",
+      "filetype": "tgz",
+      "content": "rocky9.tar.gz"
+    }
+  }
+}