cyberia 2.99.8 → 3.0.2

package/{cli.md → CLI-HELP.md}

@@ -1,4 +1,4 @@
-## underpost ci/cd cli v2.99.8
+## underpost ci/cd cli v3.0.2
 
 ### Usage: `underpost [options] [command]`
   ```
@@ -31,7 +31,7 @@ Commands:
   monitor [options] <deploy-id> [env]                        Manages health server monitoring for specified deployments.
   ssh [options]                                              Manages SSH credentials and sessions for remote access to cluster nodes or services.
   run [options] <runner-id> [path]                           Runs specified scripts using various runners.
-  lxd [options]                                              Manages LXD containers and virtual machines.
+  lxd [options]                                              Manages LXD virtual machines as K3s nodes (control plane or workers).
   baremetal [options] [workflow-id]                          Manages baremetal server operations, including installation, database setup, commissioning, and user management.
   help [command]                                             display help for command
  
@@ -370,6 +370,8 @@ Options:
                                        4.4 service.
   --valkey                             Initializes the cluster with a Valkey
                                        service.
+  --ipfs                               Initializes the cluster with an
+                                       ipfs-cluster statefulset.
   --contour                            Initializes the cluster with Project
                                        Contour base HTTPProxy and Envoy.
   --cert-manager                       Initializes the cluster with a Let's
@@ -377,8 +379,6 @@ Options:
   --dedicated-gpu                      Initializes the cluster with dedicated
                                        GPU base resources and environment
                                        settings.
-  --full                               Initializes the cluster with all
-                                       available statefulsets and services.
   --ns-use <ns-name>                   Switches the current Kubernetes context
                                        to the specified namespace (creates if
                                        it doesn't exist).
@@ -408,7 +408,6 @@ Options:
                                        by init-host.
   --config                             Sets the base Kubernetes node
                                        configuration.
-  --worker                             Sets the context for a worker node.
   --chown                              Sets the appropriate ownership for
                                        Kubernetes kubeconfig files.
   --k3s                                Initializes the cluster using K3s
@@ -419,6 +418,8 @@ Options:
                                        after execution.
   --namespace <namespace>              Kubernetes namespace for cluster
                                        operations (defaults to "default").
+  --replicas <replicas>                Sets a custom number of replicas for
+                                       statefulset deployments.
   -h, --help                           display help for command
  
 ```
@@ -491,6 +492,9 @@ Options:
                                       deployment operations.
   --port <port>                       Sets up port forwarding from local to
                                       remote ports.
+  --expose-port <port>                Sets the local:remote port to expose when
+                                      --expose is active (overrides
+                                      auto-detected service port).
   --cmd <cmd>                         Custom initialization command for
                                       deployment (comma-separated commands).
   -h, --help                          display help for command
@@ -829,7 +833,7 @@ Options:
 Runs specified scripts using various runners.
 
 Arguments:
-  runner-id                                       The runner ID to run. Options: dev-cluster,metadata,svc-ls,svc-rm,ssh-deploy-info,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,ls-deployments,host-update,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,sh,log,ps,ptls,release-cmt,deploy-test,sync-replica,tf-vae-test,spark-template,rmi,kill,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job.
+  runner-id                                       The runner ID to run. Options: dev-cluster,ipfs-expose,metadata,svc-ls,svc-rm,ssh-deploy-info,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,ls-deployments,host-update,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,etc-hosts,sh,log,ps,ptls,release-cmt,deploy-test,sync-replica,tf-vae-test,spark-template,rmi,kill,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job.
   path                                            The input value, identifier, or path for the operation.
 
 Options:
@@ -904,47 +908,48 @@ Options:
 ```
  Usage: underpost lxd [options]
 
-Manages LXD containers and virtual machines.
+Manages LXD virtual machines as K3s nodes (control plane or workers).
 
 Options:
-  --init                           Initializes LXD on the current machine.
-  --reset                          Resets LXD on the current machine, deleting
-                                   all configurations.
-  --install                        Installs LXD on the current machine.
-  --dev                            Sets the development context environment for
-                                   LXD.
-  --create-virtual-network         Creates an LXD virtual network bridge.
-  --create-admin-profile           Creates an admin profile for LXD management.
-  --control                        Sets the context for a control node VM.
-  --worker                         Sets the context for a worker node VM.
-  --create-vm <vm-id>              Creates default virtual machines with the
-                                   specified ID.
-  --init-vm <vm-id>                Retrieves the Underpost initialization
-                                   script for the specified VM.
-  --info-vm <vm-id>                Retrieves all information about the
+  --init                           Initializes LXD on the current machine via
+                                   preseed.
+  --reset                          Removes the LXD snap and purges all data.
+  --install                        Installs the LXD snap.
+  --dev                            Use local paths instead of the global npm
+                                   installation.
+  --create-virtual-network         Creates the lxdbr0 bridge network.
+  --ipv4-address <cidr>            IPv4 address/CIDR for the lxdbr0 bridge
+                                   network (default: "10.250.250.1/24").
+  --create-admin-profile           Creates the admin-profile for VM management.
+  --control                        Initialize the target VM as a K3s control
+                                   plane node.
+  --worker                         Initialize the target VM as a K3s worker
+                                   node.
+  --create-vm <vm-name>            Copy the LXC launch command for a new K3s VM
+                                   to the clipboard.
+  --delete-vm <vm-name>            Stop and delete the specified VM.
+  --init-vm <vm-name>              Run k3s-node-setup.sh on the specified VM
+                                   (use with --control or --worker).
+  --info-vm <vm-name>              Display full configuration and status for
+                                   the specified VM.
+  --test <vm-name>                 Run connectivity and health checks on the
                                    specified VM.
-  --test <vm-id>                   Tests the health, status, and network
-                                   connectivity for a VM.
-  --root-size <gb-size>            Sets the root partition size (in GB) for the
-                                   VM.
-  --k3s                            Flag to indicate that the VM initialization
-                                   is for a K3s cluster type.
-  --join-node <nodes>              A comma-separated list of worker and control
-                                   nodes to join (e.g.,
-                                   "k8s-worker-1,k8s-control").
-  --expose <vm-name-ports>         Exposes specified ports on a VM (e.g.,
-                                   "k8s-control:80,443"). Multiple VM-port
-                                   pairs can be comma-separated.
-  --delete-expose <vm-name-ports>  Removes exposed ports on a VM (e.g.,
-                                   "k8s-control:80,443"). Multiple VM-port
-                                   pairs can be comma-separated.
-  --workflow-id <workflow-id>      Sets the workflow ID context for LXD
-                                   operations.
-  --vm-id <vm-id>                  Sets the VM ID context for LXD operations.
-  --deploy-id <deploy-id>          Sets the deployment ID context for LXD
-                                   operations.
-  --namespace <namespace>          Kubernetes namespace for LXD operations
-                                   (defaults to "default").
+  --root-size <gb-size>            Root disk size in GiB for --create-vm
+                                   (default: 32).
+  --join-node <nodes>              Join a K3s worker to a control plane.
+                                   Standalone format: "workerName,controlName".
+                                   When used with --init-vm --worker, provide
+                                   just the control node name for auto-join.
+  --expose <vm-name:ports>         Proxy host ports to a VM (e.g.,
+                                   "k3s-control:80,443").
+  --delete-expose <vm-name:ports>  Remove proxied ports from a VM (e.g.,
+                                   "k3s-control:80,443").
+  --workflow-id <workflow-id>      Workflow ID to execute via runWorkflow.
+  --vm-id <vm-name>                Target VM name for workflow execution.
+  --deploy-id <deploy-id>          Deployment ID context for workflow
+                                   execution.
+  --namespace <namespace>          Kubernetes namespace context (defaults to
+                                   "default").
   -h, --help                       display help for command
  
 ```

package/README.md

@@ -24,12 +24,14 @@ Key features:
 
 - Walks the asset directory structure and processes PNG/GIF files.
 - Produces `frame_matrix` and `map_color` arrays from images.
+- **Procedurally generates object layers** from semantic item-id descriptors with deterministic seeds and temporal coherence.
 - Saves processed objects to the `ObjectLayer` model with top-level references to `ObjectLayerRenderFrames`.
 - Creates separate `ObjectLayerRenderFrames` documents for render data.
 - Links ObjectLayers to AtlasSpriteSheet documents via top-level `atlasSpriteSheetId`.
 - Generates unique UUID v4 seeds (via `crypto.randomUUID()`) for SHA256 hash uniqueness.
 - Generates SHA256 hash using `fast-json-stable-stringify` for deterministic serialization.
 - Reconstructs PNG frames from stored tile data for debugging.
+- Writes static asset PNGs, atlas sprite sheets, and metadata to the conventional directory structure.
 
 ## Getting Started
 
@@ -68,6 +70,104 @@ cyberia ol --import skin,floor
 cyberia ol --import all
 ```
 
+### Procedural generation with `--generate`
+
+Produces semantically consistent object layers with controlled, reproducible variation and short-term temporal coherence (consecutive frames stay visually consistent). Uses the parametric shape generator and object layer engine under the hood.
+
+```bash
+# Generate a desert floor tile (single frame, auto seed)
+cyberia ol floor-desert --generate
+
+# Full control: 3 frames, explicit seed, density
+cyberia ol floor-desert --generate --count 3 --seed fx-42 --frame-index 0 --frame-count 3 --density 0.5
+
+# Grass terrain, sparse, 5 frames
+cyberia ol floor-grass --generate --seed meadow-7 --frame-count 5 --density 0.3
+
+# Water surface, dense, high element count
+cyberia ol floor-water --generate --seed ocean-1 --count 5 --density 0.8 --frame-count 4
+
+# Stone cobblestone
+cyberia ol floor-stone --generate --seed cobble-99 --count 4 --density 0.6
+
+# Lava flow, 3-frame animation
+cyberia ol floor-lava --generate --seed magma-3 --frame-count 3 --density 0.7
+```
+
+**`--generate` options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `--seed <str>` | auto UUID | Deterministic seed string. Same seed → same output. |
+| `--count <n>` | `3` | Shape element count multiplier per layer. |
+| `--frame-index <n>` | `0` | Starting frame index. |
+| `--frame-count <n>` | `1` | Number of consecutive frames to generate. |
+| `--density <f>` | `0.5` | Overall density factor (`0`–`1`). Lower = sparser. |
+
+**Available semantic item-id prefixes:**
+
+| Prefix | Type | Tags | Palette |
+|---|---|---|---|
+| `floor-desert` | floor | sand, dune, arid | warm ochres, sand tones |
+| `floor-grass` | floor | grass, meadow, earth | greens, earth browns |
+| `floor-water` | floor | water, ocean, wave | blues, foam whites |
+| `floor-stone` | floor | stone, rock, cobble | greys, warm/cool stone |
+| `floor-lava` | floor | lava, magma, fire | reds, oranges, dark crust |
+| `skin-*` | skin | character, body | skin tones, clothing darks |
+
+#### How generation works
+
+Each item-id maps to a **semantic descriptor** that provides `semanticTags`, `paletteHints`, `preferredShapes`, and named **layer specs** (e.g. `base`, `dunes`, `rocks`, `tufts` for `floor-desert`).
+
+**Seed derivation** — deterministic at every level:
+
+```
+layerSeed  = hash(seed + ':' + itemId + ':' + layerKey)
+frameSeed  = hash(layerSeed + ':' + frameIndex)
+```
+
+**Temporal coherence** — shape topology (which shapes, how many, where) is locked to `layerSeed` and never changes between frames. Only smooth, low-frequency noise perturbations (position jitter, slight rotation/scale wobble) are derived from `frameSeed`, so frame N and N+1 differ by ~2% of cells.
+
+**Layer naming** — every generated layer gets an id: `<itemId>-<layerKey>` (e.g. `floor-desert-dunes`).
+
+**Generation pipeline per layer:**
+
+1. Pick generator type (`noise-field` for base fills, `shape` for element placement).
+2. Select palette colors deterministically from `paletteHints` with per-element `colorShift`.
+3. For shape layers: pick shape via weighted `preferredShapes`, compute stable base transform `(x, y, scale, rotation)`, apply frame-level smooth noise.
+4. Stamp shapes onto a 24×24 grid via `intCoords` rasterization from the parametric shape generator.
+5. Composite all layers into a final `frame_matrix` + unified `colors` palette.
+
+**Variability factors per layer:**
+`scaleVariance`, `rotationVariance`, `colorShift`, `jitter`, `noiseLevel`, `detailLevel`, `sparsity` — small, deterministic variations that keep each generation unique but semantically coherent.
+
+#### What `--generate` persists
+
+The full pipeline runs automatically:
+
+1. **Static assets** — PNGs written to `./src/client/public/cyberia/assets/{type}/{itemId}/{dirCode}/{frame}.png` + `metadata.json`.
+2. **MongoDB** — `ObjectLayerRenderFrames` + `ObjectLayer` documents created with SHA-256 hash.
+3. **Atlas sprite sheet** — generated, saved to `File` + `AtlasSpriteSheet` collections, and linked via `atlasSpriteSheetId`.
+
+#### Reproducibility example
+
+Running the same command twice produces byte-identical output:
+
+```bash
+# Run 1
+cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+
+# Run 2 (identical output)
+cyberia ol floor-desert --generate --seed fx-42 --count 3 --frame-count 2
+```
+
+Different seeds produce different but semantically consistent results:
+
+```bash
+cyberia ol floor-desert --generate --seed fx-42   # variant A
+cyberia ol floor-desert --generate --seed fx-99   # variant B (same style, different arrangement)
+```
+
 ## Visualize a processed frame
 
 Reconstructs and opens a PNG from the database-stored frame data. Requires item-id as the first positional argument, followed by direction and frame index in the format `[direction]_[frameIndex]`.
@@ -178,6 +278,45 @@ cyberia ol anon --to-atlas-sprite-sheet
 cyberia ol anon --show-atlas-sprite-sheet
 ```
 
+### Procedural Generation Pipeline
+
+Generate an object layer entirely from a semantic descriptor — no source PNGs needed:
+
+```bash
+# 1. Generate a 3-frame desert floor with explicit seed
+cyberia ol floor-desert --generate --seed fx-42 --frame-count 3 --density 0.5
+
+# 2. Inspect the generated frame
+cyberia ol floor-desert --show-frame 08_0
+
+# 3. View the auto-generated atlas
+cyberia ol floor-desert --show-atlas-sprite-sheet
+```
+
+### Batch Procedural Generation
+
+Generate a full tileset family with consistent seeds:
+
+```bash
+cyberia ol floor-desert --generate --seed world-1 --frame-count 3
+cyberia ol floor-grass  --generate --seed world-1 --frame-count 3
+cyberia ol floor-water  --generate --seed world-1 --frame-count 4
+cyberia ol floor-stone  --generate --seed world-1 --frame-count 2
+cyberia ol floor-lava   --generate --seed world-1 --frame-count 3
+```
+
+### Exploring Seed Variations
+
+```bash
+# Same item, different seeds — compare visual output
+cyberia ol floor-desert --generate --seed alpha  --frame-count 1
+cyberia ol floor-desert --generate --seed beta   --frame-count 1
+cyberia ol floor-desert --generate --seed gamma  --frame-count 1
+
+# Inspect each
+cyberia ol floor-desert --show-frame 08_0
+```
+
 ### Debugging Asset Issues
 
 ```bash

package/bin/build.js

@@ -10,13 +10,6 @@ if (fs.existsSync(baseConfPath)) dotenv.config({ path: baseConfPath, override: t
 
 const logger = loggerFactory(import.meta);
 
-// (async () => {
-//   return;
-//   const files = await fs.readdir(`./src`);
-//   for (const relativePath of files) {
-//   }
-// })();
-
 const confName = process.argv[2];
 const basePath = '../pwa-microservices-template';
 const repoName = `engine-${confName.split('dd-')[1]}`;
@@ -24,20 +17,13 @@ const deployList = (confName === 'dd' ? fs.readFileSync(`./engine-private/deploy
   ',',
 );
 
-logger.info('', {
+logger.info('Build repository', {
   confName,
   repoName,
   basePath,
   deployList,
 });
 
-if (process.argv.includes('clean')) {
-  if (fs.existsSync(`${basePath}/images`)) fs.copySync(`${basePath}/images`, `./images`);
-  shellExec(`cd ${basePath} && git checkout .`);
-  shellExec(`cd ${basePath} && git clean -f -d`);
-  process.exit(0);
-}
-
 if (process.argv.includes('conf')) {
   for (const _confName of deployList) {
     const _repoName = `engine-${_confName.split('dd-')[1]}`;
@@ -186,6 +172,7 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         ...packageJson.dependencies,
         ...CyberiaDependencies,
       };
+      packageJson.overrides = originPackageJson.overrides;
       fs.writeFileSync(`${basePath}/bin/index.js`, fs.readFileSync(`./bin/cyberia.js`, 'utf8'), 'utf8');
       fs.copyFileSync(`./src/api/object-layer/README.md`, `${basePath}/README.md`);
       fs.copySync(`./hardhat`, `${basePath}/hardhat`);
@@ -194,6 +181,9 @@ const { DefaultConf } = await import(`../conf.${confName}.js`);
         '/src/client/ssr/pages/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',
+        '/test/shape-generator.test.js',
       ])
         fs.copySync(`.${path}`, `${basePath}${path}`);
 
@@ -230,4 +220,6 @@ 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]}`);
   }
+  shellExec(`cd ${basePath} && npm install --ignore-scripts`);
+  shellExec(`cd ${basePath} && npm run fix`);
 }