cyberia 3.2.5 → 3.2.12

package/src/server/process.js

@@ -1,38 +1,55 @@
 /**
  * Module for process and shell command management.
- * Provides utilities for executing shell commands, managing signals, and handling environment details.
+ * Provides utilities for executing shell commands, managing signals, and
+ * handling environment details.
+ *
+ * Execution semantics:
+ *   - `shellExec(cmd)` throws `ShellExecError` on non-zero exit (fail-fast
+ *     is the default). CI/CD chains observe the failure end-to-end.
+ *   - `shellExec(cmd, { silentOnError: true })` opts out — returns the
+ *     `ShellString` result with `.code/.stdout/.stderr` so callers can
+ *     branch on the exit code themselves. Use for existence checks
+ *     (`test -x …`, `command -v …`, `kubectl get` when "missing" is a
+ *     normal answer).
+ *   - `shellExec(cmd, { cwd: "..." })` runs hermetically in `cwd` without
+ *      touching shelljs's global state.
+ *   - All children spawned by `shellExec` register in
+ *     `ProcessController.children` so SIGINT/SIGTERM forwarding can reach
+ *     them before the parent exits.
+ *
  * @module src/server/process.js
  * @namespace Process
  */
-
 // https://nodejs.org/api/process
-
 import shell from 'shelljs';
 import { loggerFactory } from './logger.js';
 import clipboard from 'clipboardy';
 import Underpost from '../index.js';
 import { getNpmRootPath } from './conf.js';
-
 const logger = loggerFactory(import.meta);
-
 /**
  * Gets the current working directory, replacing backslashes with forward slashes for consistency.
  * @memberof Process
  * @returns {string} The root directory path.
  */
 const getRootDirectory = () => process.cwd().replace(/\\/g, '/');
-
 /**
  * Controls and manages process-level events and signals.
+ *
+ * Subprocess registry: any child process tracked here will receive
+ * SIGTERM (followed by SIGKILL after a short grace period) when the
+ * parent receives SIGINT or SIGTERM. This prevents orphaned children
+ * during Ctrl+C in dev and during pod-termination in K8S.
+ *
  * @namespace ProcessController
  */
-const ProcessController = {
+class ProcessController {
   /**
    * List of signals to listen for for graceful shutdown/handling.
    * @memberof ProcessController
    * @type {string[]}
    */
-  SIG: [
+  static SIG = [
     'SIGPIPE',
     'SIGHUP',
     'SIGTERM',
@@ -45,29 +62,65 @@ const ProcessController = {
     'SIGFPE',
     'SIGSEGV',
     'SIGILL',
-  ],
+  ];
+
+  /**
+   * Registry of currently running tracked child processes.
+   * Populated when callers spawn via the streaming Node-native path
+   * (future expansion). The sets are exposed so signal handlers and
+   * test harnesses can introspect / clean up the registry.
+   */
+  static children = new Set();
+
+  /** Internal: forward terminating signals to all tracked children. */
+  static _forwardToChildren(sig) {
+    if (ProcessController.children.size === 0) return;
+    for (const child of [...ProcessController.children]) {
+      try {
+        if (!child.killed) child.kill(sig);
+      } catch (_) {
+        // child may already have exited; ignore.
+      }
+    }
+    // Hard SIGKILL after 5s grace if any child is still alive.
+    setTimeout(() => {
+      for (const child of [...ProcessController.children]) {
+        try {
+          if (!child.killed) child.kill('SIGKILL');
+        } catch (_) {
+          /* noop */
+        }
+      }
+    }, 5000).unref();
+  }
 
   /**
    * Sets up listeners for various process signals defined in {@link ProcessController.SIG}.
-   * Handles graceful exit on 'SIGINT' (Ctrl+C).
+   * Handles graceful exit on 'SIGINT' (Ctrl+C) — but first forwards the
+   * signal to every tracked child so they get a chance to clean up.
    * @memberof ProcessController
    * @returns {Array<process.Process>} An array of process listener handles.
    */
-  onSigListen: function () {
-    return this.SIG.map((sig) =>
+  static onSigListen() {
+    return ProcessController.SIG.map((sig) =>
       process.on(sig, (...args) => {
-        this.logger.info(`process on ${sig}`, args);
+        ProcessController.logger.info(`process on ${sig}`, args);
         switch (sig) {
           case 'SIGINT':
-            return process.exit();
-
+          case 'SIGTERM':
+          case 'SIGHUP':
+            ProcessController._forwardToChildren('SIGTERM');
+            // Give children a moment to exit cleanly before our own exit.
+            if (sig === 'SIGINT') {
+              setTimeout(() => process.exit(130), 200).unref();
+            }
+            break;
           default:
             break;
         }
       }),
     );
-  },
-
+  }
   /**
    * Initializes the ProcessController.
    * Sets up signal listeners, registers a listener for the 'exit' event, and cleans up temporary deployment environment variables.
@@ -75,39 +128,115 @@ const ProcessController = {
    * @param {Object} logger - The logger instance to use for internal logging.
    * @returns {void}
    */
-  init: function (logger) {
-    this.logger = logger;
+  static init(logger) {
+    ProcessController.logger = logger;
     process.on('exit', (...args) => {
-      this.logger.info(`process on exit`, args);
+      ProcessController.logger.info(`process on exit`, args);
+      // Last-chance reap: any tracked child still alive at exit time
+      // gets a hard kill so the parent does not leak orphans into the
+      // pod / shell session.
+      ProcessController._forwardToChildren('SIGKILL');
     });
-    this.onSigListen();
-    Underpost.env.delete('await-deploy');
-  },
-};
-
+    ProcessController.onSigListen();
+  }
+}
+/**
+ * `ShellExecError` — thrown by `shellExec` when the underlying command
+ * exits with a non-zero code (the default fail-fast behaviour). Carries
+ * the exit code, stdout, and stderr for inspection by callers / CI
+ * pipelines that need structured failure data.
+ */
+class ShellExecError extends Error {
+  constructor(cmd, code, stdout, stderr) {
+    super(`shellExec failed (exit=${code}): ${cmd}`);
+    this.name = 'ShellExecError';
+    this.cmd = cmd;
+    this.code = code;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+}
 /**
  * Executes a shell command using shelljs.
+ *
+ * **Default behaviour is fail-fast**: a non-zero exit code throws
+ * `ShellExecError`. Callers that need to branch on the exit code
+ * (existence checks, optional commands) must pass `silentOnError: true`
+ * to opt out of throwing.
+ *
+ * The async-callback path is exempt from the throw — shelljs delivers
+ * `(code, stdout, stderr)` to the callback, which owns its own error
+ * handling.
+ *
  * @memberof Process
  * @param {string} cmd - The command string to execute.
  * @param {Object} [options] - Options for execution.
- * @param {boolean} [options.silent=false] - Suppress output from shell commands.
- * @param {boolean} [options.async=false] - Run command asynchronously.
- * @param {boolean} [options.stdout=false] - Return stdout content (string) instead of shelljs result object.
- * @param {boolean} [options.disableLog=false] - Prevent logging of the command.
- * @param {Function} [options.callback=null] - Callback function for asynchronous execution.
- * @returns {string|shelljs.ShellString} The result of the shell command (string if `stdout: true`, otherwise a ShellString object).
+ * @param {boolean} [options.silent=false] - Suppress child stdout/stderr to the parent terminal.
+ * @param {boolean} [options.async=false] - Run the command asynchronously (use with `callback`).
+ * @param {boolean} [options.stdout=false] - Return stdout string instead of the `ShellString` result object.
+ * @param {boolean} [options.disableLog=false] - Skip the `[process] cmd …` info log line.
+ * @param {Function} [options.callback=null] - Async callback `(code, stdout, stderr) => void` when `async: true`.
+ * @param {boolean} [options.silentOnError=false] - When `true`, swallow non-zero exits and return the `ShellString` instead of throwing. Inverse of the previous `throwOnError` flag.
+ * @param {string} [options.cwd] - Hermetic working directory (snapshotted + restored — does NOT leak).
+ * @returns {string|shelljs.ShellString} `ShellString` by default; the stdout string when `stdout: true`.
+ * @throws {ShellExecError} On non-zero exit when `silentOnError` is not set.
  */
-const shellExec = (
-  cmd,
-  options = { silent: false, async: false, stdout: false, disableLog: false, callback: null },
-) => {
+const shellExec = (cmd, options = {}) => {
   if (!options.disableLog) logger.info(`cmd`, cmd);
-  if (options.callback) return shell.exec(cmd, options, options.callback);
-  return options.stdout ? shell.exec(cmd, options).stdout : shell.exec(cmd, options);
-};
 
+  // Whitelist exactly the keys `shelljs.exec` understands. Passing our own
+  // bookkeeping keys through (or a literal `cwd: undefined`) makes shelljs
+  // call `path.resolve(undefined)` and crash with ERR_INVALID_ARG_TYPE.
+  const shellOpts = {};
+  if (options.silent !== undefined) shellOpts.silent = options.silent;
+  if (options.async !== undefined) shellOpts.async = options.async;
+
+  // Hermetic cwd. shelljs.cd mutates a process-wide global; instead we
+  // snapshot the current cwd here, switch for the duration of this call,
+  // and restore in `finally`. We deliberately do NOT forward `cwd` to
+  // shelljs — leaving its `cwd` unset means it inherits our just-changed
+  // `process.cwd()`, and we keep full control of restore semantics.
+  const previousCwd = options.cwd ? process.cwd() : null;
+  if (options.cwd) {
+    try {
+      process.chdir(options.cwd);
+    } catch (err) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, -1, '', `chdir(${options.cwd}) failed: ${err.message}`);
+    }
+  }
+  try {
+    if (options.callback) {
+      // Async path. shelljs invokes the callback with (code, stdout, stderr).
+      // The callback owns its own error handling; the throw default does
+      // not apply here.
+      return shell.exec(cmd, shellOpts, options.callback);
+    }
+    const result = shell.exec(cmd, shellOpts);
+
+    if (!options.silentOnError && result && typeof result.code === 'number' && result.code !== 0) {
+      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      throw new ShellExecError(cmd, result.code, result.stdout || '', result.stderr || '');
+    }
+
+    return options.stdout ? result.stdout : result;
+  } finally {
+    if (previousCwd) {
+      try {
+        process.chdir(previousCwd);
+      } catch (_) {
+        /* best-effort restore */
+      }
+    }
+  }
+};
 /**
  * Changes the current working directory using shelljs.
+ *
+ * Note: `shellCd` mutates global state. Prefer `shellExec(cmd, { cwd })`
+ * for one-shot directory-scoped commands; use `shellCd` only for the
+ * outermost shell where the cwd should persist across many calls.
+ *
  * @memberof Process
  * @param {string} cd - The path to change the directory to.
  * @param {Object} [options] - Options for the CD operation.
@@ -118,25 +247,35 @@ const shellCd = (cd, options = { disableLog: false }) => {
   if (!options.disableLog) logger.info(`cd`, cd);
   return shell.cd(cd);
 };
-
 /**
  * Wraps a command to run it as a daemon process in a shell (keeping the process alive/terminal open).
+ *
+ * NB: callers must ensure `cmd` does not contain unescaped single quotes —
+ * the wrapper uses `bash -c '<cmd>; …'`. For arbitrary user input prefer
+ * a heredoc or a temporary script file.
+ *
  * @memberof Process
  * @param {string} cmd - The command to daemonize.
  * @returns {string} The shell command string for the daemon process.
  */
 const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
-
 /**
  * Retrieves the process ID (PID) of the most recently created gnome-terminal instance.
  * Note: This function is environment-specific (GNOME/Linux) and uses `pgrep -n`.
  * @memberof Process
- * @returns {number} The PID of the last gnome-terminal process.
+ * @returns {number|null} The PID of the last gnome-terminal process, or null if none running.
  */
 // list all terminals: pgrep gnome-terminal
 // list last terminal: pgrep -n gnome-terminal
-const getTerminalPid = () => JSON.parse(shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true }));
-
+const getTerminalPid = () => {
+  const raw = shellExec(`pgrep -n gnome-terminal`, { stdout: true, silent: true, silentOnError: true });
+  if (!raw || !raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
 /**
  * Copies text content to the system clipboard using clipboardy.
  * Logs the copied content for confirmation.
@@ -148,5 +287,13 @@ function pbcopy(data) {
   clipboard.writeSync(data || '🦄');
   logger.info(`copied to clipboard`, clipboard.readSync());
 }
-
-export { ProcessController, getRootDirectory, shellExec, shellCd, pbcopy, getTerminalPid, daemonProcess };
+export {
+  ProcessController,
+  ShellExecError,
+  getRootDirectory,
+  shellExec,
+  shellCd,
+  pbcopy,
+  getTerminalPid,
+  daemonProcess,
+};

package/src/server/proxy.js

@@ -9,7 +9,14 @@
 import express from 'express';
 import { createProxyMiddleware } from 'http-proxy-middleware';
 import { loggerFactory, loggerMiddleware } from './logger.js';
-import { buildPortProxyRouter, buildProxyRouter, getTlsHosts, isDevProxyContext, isTlsDevProxy } from './conf.js';
+import {
+  buildPortProxyRouter,
+  buildProxyRouter,
+  etcHostFactory,
+  getTlsHosts,
+  isDevProxyContext,
+  isTlsDevProxy,
+} from './conf.js';
 
 import { shellExec } from './process.js';
 import fs from 'fs-extra';
@@ -114,7 +121,7 @@ class ProxyService {
       logger.info('Proxy running', { port, router: options.router });
       if (process.env.NODE_ENV === 'development')
         logger.info(
-          Underpost.deploy.etcHostFactory(Object.keys(options.router), {
+          etcHostFactory(Object.keys(options.router), {
             append: true,
           }).renderHosts,
         );

package/src/server/runtime.js

@@ -176,7 +176,7 @@ const buildRuntime = async () => {
   }
 
   if (Lampp.enabled() && Lampp.router) Lampp.initService();
-
+  Underpost.env.delete('await-deploy');
   Underpost.start.logRuntimeRouter();
 };
 

package/src/server/semantic-layer-generator-floor.js

@@ -5,10 +5,16 @@
  * desert, grass, water, stone, and lava.  Imported by the main
  * semantic-layer-generator.js which registers them at startup.
  *
+ * Biome palettes are imported from the centralized BIOME_PALETTES in the
+ * parent module (circular import is safe because the function body is only
+ * executed after module initialisation completes).
+ *
  * @module src/server/semantic-layer-generator-floor.js
  * @namespace SemanticLayerGeneratorFloor
  */
 
+import { BIOME_PALETTES } from './semantic-layer-generator.js';
+
 /* ═══════════════════════════════════════════════════════════════════════════
  *  FLOOR SEMANTIC REGISTRY
  *  Call registerFloorSemantics(registerFn) once to add all floor descriptors.
@@ -16,7 +22,6 @@
 
 /**
  * Registers all built-in floor semantic descriptors.
- * Uses dependency injection — no import from the parent module.
  *
  * @param {function(string, import('./semantic-layer-generator.js').SemanticDescriptor): void} registerFn
  * @memberof SemanticLayerGeneratorFloor
@@ -25,16 +30,7 @@ export function registerFloorSemantics(registerFn) {
   /* ── Desert ───────────────────────────────────────────────────────────── */
   registerFn('floor-desert', {
     semanticTags: ['sand', 'dune', 'arid', 'dry'],
-    paletteHints: [
-      [210, 180, 120, 255],
-      [194, 160, 100, 255],
-      [230, 205, 150, 255],
-      [180, 140, 80, 255],
-      [160, 120, 70, 255],
-      [120, 90, 55, 255],
-      [100, 80, 50, 255],
-      [240, 220, 175, 255],
-    ],
+    paletteHints: BIOME_PALETTES.desert,
     preferredShapes: { ellipse: 3, circle: 2, cactus: 1, star: 0.5 },
     itemType: 'floor',
     layers: {
@@ -104,16 +100,7 @@ export function registerFloorSemantics(registerFn) {
   /* ── Grass ────────────────────────────────────────────────────────────── */
   registerFn('floor-grass', {
     semanticTags: ['grass', 'meadow', 'green', 'earth'],
-    paletteHints: [
-      [80, 140, 60, 255],
-      [60, 120, 45, 255],
-      [110, 170, 80, 255],
-      [90, 130, 55, 255],
-      [130, 100, 65, 255],
-      [70, 110, 40, 255],
-      [150, 190, 100, 255],
-      [100, 85, 50, 255],
-    ],
+    paletteHints: BIOME_PALETTES.grass,
     preferredShapes: { ellipse: 3, circle: 2, heart: 0.5 },
     itemType: 'floor',
     layers: {
@@ -168,16 +155,7 @@ export function registerFloorSemantics(registerFn) {
   /* ── Water ────────────────────────────────────────────────────────────── */
   registerFn('floor-water', {
     semanticTags: ['water', 'ocean', 'wave', 'liquid'],
-    paletteHints: [
-      [40, 100, 180, 255],
-      [60, 130, 200, 255],
-      [90, 160, 220, 255],
-      [120, 190, 230, 255],
-      [30, 80, 150, 255],
-      [70, 140, 210, 255],
-      [150, 210, 240, 255],
-      [20, 60, 120, 255],
-    ],
+    paletteHints: BIOME_PALETTES.water,
     preferredShapes: { ellipse: 3, circle: 2 },
     itemType: 'floor',
     layers: {
@@ -232,16 +210,7 @@ export function registerFloorSemantics(registerFn) {
   /* ── Stone ────────────────────────────────────────────────────────────── */
   registerFn('floor-stone', {
     semanticTags: ['stone', 'rock', 'cobble', 'grey'],
-    paletteHints: [
-      [140, 140, 145, 255],
-      [120, 118, 125, 255],
-      [165, 165, 170, 255],
-      [100, 98, 105, 255],
-      [180, 180, 185, 255],
-      [90, 85, 80, 255],
-      [155, 150, 148, 255],
-      [110, 108, 115, 255],
-    ],
+    paletteHints: BIOME_PALETTES.stone,
     preferredShapes: { circle: 3, ellipse: 2, star: 1, 'pixel-art': 0.5 },
     itemType: 'floor',
     layers: {
@@ -296,16 +265,7 @@ export function registerFloorSemantics(registerFn) {
   /* ── Lava ─────────────────────────────────────────────────────────────── */
   registerFn('floor-lava', {
     semanticTags: ['lava', 'magma', 'fire', 'hot'],
-    paletteHints: [
-      [200, 50, 20, 255],
-      [230, 100, 30, 255],
-      [255, 180, 50, 255],
-      [160, 30, 10, 255],
-      [80, 20, 10, 255],
-      [50, 15, 8, 255],
-      [240, 140, 40, 255],
-      [120, 25, 12, 255],
-    ],
+    paletteHints: BIOME_PALETTES.lava,
     preferredShapes: { circle: 3, ellipse: 2, cactus: 1 },
     itemType: 'floor',
     layers: {