underpost 3.2.5 → 3.2.8

package/src/server/process.js

@@ -4,35 +4,30 @@
  * @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.
  * @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 +40,26 @@ const ProcessController = {
     'SIGFPE',
     'SIGSEGV',
     'SIGILL',
-  ],
-
+  ];
   /**
    * Sets up listeners for various process signals defined in {@link ProcessController.SIG}.
    * Handles graceful exit on 'SIGINT' (Ctrl+C).
    * @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();
-
           default:
             break;
         }
       }),
     );
-  },
-
+  }
   /**
    * Initializes the ProcessController.
    * Sets up signal listeners, registers a listener for the 'exit' event, and cleans up temporary deployment environment variables.
@@ -75,16 +67,15 @@ 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);
     });
-    this.onSigListen();
+    ProcessController.onSigListen();
     Underpost.env.delete('await-deploy');
-  },
-};
-
+  }
+}
 /**
  * Executes a shell command using shelljs.
  * @memberof Process
@@ -105,7 +96,6 @@ const shellExec = (
   if (options.callback) return shell.exec(cmd, options, options.callback);
   return options.stdout ? shell.exec(cmd, options).stdout : shell.exec(cmd, options);
 };
-
 /**
  * Changes the current working directory using shelljs.
  * @memberof Process
@@ -118,7 +108,6 @@ 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).
  * @memberof Process
@@ -126,7 +115,6 @@ const shellCd = (cd, options = { disableLog: false }) => {
  * @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`.
@@ -136,7 +124,6 @@ const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
 // 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 }));
-
 /**
  * Copies text content to the system clipboard using clipboardy.
  * Logs the copied content for confirmation.
@@ -148,5 +135,4 @@ function pbcopy(data) {
   clipboard.writeSync(data || '🦄');
   logger.info(`copied to clipboard`, clipboard.readSync());
 }
-
 export { ProcessController, getRootDirectory, shellExec, shellCd, pbcopy, getTerminalPid, daemonProcess };

package/src/server/start.js

@@ -131,11 +131,13 @@ class UnderpostStartUp {
      * @param {boolean} options.build - Whether to build the deployment.
      * @param {boolean} options.run - Whether to run the deployment.
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
+     * @param {boolean} options.skipPullBase - Whether to skip pulling the base code.
+     * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
      */
     async callback(
       deployId = 'dd-default',
       env = 'development',
-      options = { build: false, run: false, underpostQuicklyInstall: false },
+      options = { build: false, run: false, underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false },
     ) {
       Underpost.env.set('container-status', `${deployId}-${env}-build-deployment`);
       if (options.build === true) await Underpost.start.build(deployId, env, options);
@@ -149,12 +151,13 @@ class UnderpostStartUp {
      * @param {Object} options - Options for the build.
      * @param {boolean} options.skipPullBase - Whether to skip pulling the base code and use the current workspace code directly.
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
+     * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
      * @memberof UnderpostStartUp
      */
     async build(
       deployId = 'dd-default',
       env = 'development',
-      options = { underpostQuicklyInstall: false, skipPullBase: false },
+      options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false },
     ) {
       const buildBasePath = `/home/dd`;
       const repoName = `engine-${deployId.split('-')[1]}`;
@@ -173,7 +176,7 @@ class UnderpostStartUp {
         for (const itcScript of itcScripts)
           if (itcScript.match(deployId)) shellExec(`node ./engine-private/itc-scripts/${itcScript}`);
       }
-      shellExec(`node bin client ${deployId}`);
+      if (!options.skipFullBuild) shellExec(`node bin client ${deployId}`);
     },
     /**
      * Runs a deployment.

package/src/server/valkey.js

@@ -1,293 +1,192 @@
 /**
- * Module for managing Valkey
+ * Valkey connection and key-value store module.
+ *
+ * Responsibilities:
+ *  - Manage per-instance Valkey connections keyed by `${host}${path}`.
+ *  - Provide a thin, typed CRUD surface: get / set / del / update.
+ *  - Expose connection status helpers.
+ *
+ * Out of scope: domain model factories, DTO projection — those belong in
+ * their respective service modules (e.g. guest.service.js).
+ *
  * @module src/server/valkey.js
  * @namespace ValkeyService
  */
-
 import Valkey from 'iovalkey';
-import mongoose from 'mongoose';
-import { hashPassword } from './auth.js';
 import { loggerFactory } from './logger.js';
 
 const logger = loggerFactory(import.meta);
 
-// Per-instance registries keyed by `${host}${path}`
+// ─── Instance registry ────────────────────────────────────────────────────────
+
+/** @type {Record<string, import('iovalkey').default>} */
 const ValkeyInstances = {};
-const DummyStores = {}; // in-memory Maps per instance
-const ValkeyStatus = {}; // 'connected' | 'dummy' | 'error' | undefined
+
+/** @type {Record<string, 'connected' | 'error'>} */
+const ValkeyStatus = {};
 
 /**
- * Checks if any Valkey instance is connected.
- * This is a backward-compatible overall flag.
- * @returns {boolean} True if any instance has a 'connected' status.
- * @memberof ValkeyService
+ * Derives the registry key from an instance descriptor.
+ * @param {{ host?: string, path?: string }} opts
+ * @returns {string}
  */
-const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
+const _instanceKey = (opts = {}) => `${opts.host || ''}${opts.path || ''}`;
+
+// ─── Connection ───────────────────────────────────────────────────────────────
 
 /**
- * Generates a unique key for a Valkey instance based on its host and path.
- * @param {object} [opts={ host: '', path: '' }] - The instance options.
- * @param {string} [opts.host=''] - The host of the instance.
- * @param {string} [opts.path=''] - The path of the instance.
- * @returns {string} The instance key.
- * @private
+ * Returns true when at least one Valkey instance is connected.
+ * @returns {boolean}
  * @memberof ValkeyService
  */
-const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opts.path || ''}`;
+const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
 
 /**
- * Creates and manages a connection to a Valkey server for a given instance.
- * It sets up a client, attaches event listeners for connection status, and implements a fallback to an in-memory dummy store if the connection fails.
- * @param {object} [instance={ host: '', path: '' }] - The instance identifier.
- * @param {string} [instance.host=''] - The host of the instance.
- * @param {string} [instance.path=''] - The path of the instance.
- * @param {object} [valkeyServerConnectionOptions={ host: '', path: '' }] - Connection options for the iovalkey client.
- * @returns {Promise<Valkey|undefined>} A promise that resolves to the Valkey client instance, or undefined if creation fails.
+ * Creates a Valkey client for the given instance and waits for connectivity.
+ * Throws on connection failure — callers decide whether to abort or continue
+ * without Valkey.
+ *
+ * @param {{ host?: string, path?: string }} instance - Registry key descriptor.
+ * @param {{ host?: string, port?: number }} connectionOptions - iovalkey connection options.
+ * @returns {Promise<import('iovalkey').default>}
  * @memberof ValkeyService
  */
-const createValkeyConnection = async (
-  instance = { host: '', path: '' },
-  valkeyServerConnectionOptions = { host: '', path: '' },
-) => {
+const createValkeyConnection = async (instance = {}, connectionOptions = {}) => {
   const key = _instanceKey(instance);
-  // Initialize dummy store for the instance
-  if (!DummyStores[key]) DummyStores[key] = new Map();
 
-  try {
-    const client = await ValkeyAPI.valkeyClientFactory(valkeyServerConnectionOptions);
-
-    // Attach listeners for visibility
-    client.on?.('ready', () => {
-      ValkeyStatus[key] = 'connected';
-      logger.info('Valkey connected', { instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('error', (err) => {
-      // Switch to dummy if not yet connected
-      if (ValkeyStatus[key] !== 'connected') {
-        ValkeyStatus[key] = 'dummy';
-      } else {
-        ValkeyStatus[key] = 'error';
-      }
-      logger.warn('Valkey error', { err: err?.message, instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('end', () => {
-      if (ValkeyStatus[key] !== 'dummy') ValkeyStatus[key] = 'error';
-      logger.warn('Valkey connection ended', { instance, status: ValkeyStatus[key] });
-    });
-
-    // Probe connectivity with a short timeout
-    const probe = async () => {
+  const client = new Valkey({
+    port: connectionOptions.port ?? undefined,
+    host: connectionOptions.host ?? undefined,
+    retryStrategy: (attempt) => (attempt === 1 ? undefined : 1000),
+  });
+
+  client.on('ready', () => {
+    ValkeyStatus[key] = 'connected';
+    logger.info('Valkey connected', { instance });
+  });
+  client.on('error', (err) => {
+    ValkeyStatus[key] = 'error';
+    logger.error('Valkey error', { err: err?.message, instance });
+  });
+  client.on('end', () => {
+    ValkeyStatus[key] = 'error';
+    logger.warn('Valkey connection ended', { instance });
+  });
+
+  // Verify connectivity with a probe before marking ready
+  await Promise.race([
+    (async () => {
       try {
-        // basic ping via SET/GET roundtrip
-        const probeKey = `__vk_probe_${Date.now()}`;
-        await client.set(probeKey, '1');
-        await client.get(probeKey);
+        const probe = `__vk_probe_${Date.now()}`;
+        await client.set(probe, '1');
+        await client.get(probe);
+        await client.del(probe);
         ValkeyStatus[key] = 'connected';
-      } catch (e) {
-        ValkeyStatus[key] = 'dummy';
-        logger.warn('Valkey probe failed, falling back to dummy', { instance, error: e?.message });
+      } catch {
+        ValkeyStatus[key] = 'error';
       }
-    };
-
-    // Race with timeout to avoid hanging
-    await Promise.race([probe(), new Promise((resolve) => setTimeout(resolve, 1000))]);
+    })(),
+    new Promise((resolve) => setTimeout(resolve, 1500)),
+  ]);
 
-    ValkeyInstances[key] = client;
-    if (!ValkeyStatus[key]) ValkeyStatus[key] = 'dummy';
-  } catch (err) {
-    ValkeyStatus[key] = 'dummy';
-    logger.warn('Valkey client creation failed, using dummy', { instance, error: err?.message });
-  }
-
-  return ValkeyInstances[key];
+  ValkeyInstances[key] = client;
+  logger.info('Valkey instance registered', { key, status: ValkeyStatus[key] });
+  return client;
 };
 
+// ─── Internal client resolver ─────────────────────────────────────────────────
+
 /**
- * Factory function to create a Data Transfer Object (DTO) from a payload.
- * It filters the payload to include only the keys specified in the `select` object.
- * @param {object} payload - The source object.
- * @param {object} select - An object where keys are field names and values are 1 to include them.
- * @returns {object} A new object containing only the selected fields from the payload.
- * @memberof ValkeyService
+ * Resolves the connected client for an instance or throws.
+ * @param {{ host?: string, path?: string }} options
+ * @returns {import('iovalkey').default}
  */
-const selectDtoFactory = (payload, select) => {
-  const result = {};
-  for (const key of Object.keys(select)) {
-    if (select[key] === 1 && key in payload) result[key] = payload[key];
+const _client = (options) => {
+  const k = _instanceKey(options);
+  const client = ValkeyInstances[k];
+  if (!client || ValkeyStatus[k] !== 'connected') {
+    throw new Error(`Valkey instance not connected: ${k}`);
   }
-  return result;
+  return client;
 };
 
-/**
- * Factory function to create a new Valkey client instance.
- * @param {object} options - Connection options for the iovalkey client.
- * @returns {Promise<Valkey>} A promise that resolves to a new Valkey client.
- * @memberof ValkeyService
- */
-const valkeyClientFactory = async (options) => {
-  const valkey = new Valkey({
-    port: options?.port ? options.port : undefined,
-    host: options?.host ? options.host : undefined,
-    // Keep retry strategy minimal; state handled in createValkeyConnection
-    retryStrategy: (attempt) => {
-      if (attempt === 1) return undefined; // stop aggressive retries early
-      return 1000; // retry interval if library continues
-    },
-  }); // Connect to 127.0.0.1:6379
-  // new Valkey(6380); // 127.0.0.1:6380
-  // new Valkey(6379, '192.168.1.1'); // 192.168.1.1:6379
-  // new Valkey('/tmp/redis.sock');
-  // new Valkey({
-  //   port: 6379, // Valkey port
-  //   host: '127.0.0.1', // Valkey host
-  //   username: 'default', // needs Valkey >= 6
-  //   password: 'my-top-secret',
-  //   db: 0, // Defaults to 0
-  // });
-  return valkey;
-};
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
 
 /**
- * Retrieves an object from Valkey by key for a specific instance.
- * If the Valkey client is not connected or an error occurs, it falls back to the dummy in-memory store.
- * It automatically parses JSON strings.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to retrieve.
- * @returns {Promise<object|string|null>} A promise that resolves to the retrieved object, string, or null if not found.
+ * Retrieves and JSON-parses a value by key.
+ * Returns null when the key does not exist.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<object | string | null>}
  * @memberof ValkeyService
  */
-const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
-  const k = _instanceKey(options);
-  const status = ValkeyStatus[k];
+const get = async (options, key) => {
+  const raw = await _client(options).get(key);
+  if (raw == null) return null;
   try {
-    if (status === 'connected' && ValkeyInstances[k]) {
-      const value = await ValkeyInstances[k].get(key);
-      if (value == null) return null;
-      try {
-        return JSON.parse(value);
-      } catch {
-        // not JSON, return raw string
-        return value;
-      }
-    }
-  } catch (err) {
-    logger.warn('Valkey get failed, using dummy', { key, err: err?.message });
+    return JSON.parse(raw);
+  } catch {
+    return raw;
   }
-  // Dummy fallback returns stored value as-is (string or object)
-  return DummyStores[k]?.get(key) ?? null;
 };
 
 /**
- * Sets an object or string in Valkey for a specific instance.
- * If the Valkey client is not connected, it writes to the in-memory dummy store instead.
- * Objects are automatically stringified.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key under which to store the payload.
- * @param {object|string} [payload={}] - The data to store.
- * @returns {Promise<string>} A promise that resolves to 'OK' on success.
+ * Serialises and stores a value by key.
+ * Pass `ttlMs` to set an expiry in milliseconds.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object | string} payload
+ * @param {number} [ttlMs]
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const setValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  const k = _instanceKey(options);
-  const isString = typeof payload === 'string';
-  const value = isString ? payload : JSON.stringify(payload);
-  try {
-    if (ValkeyStatus[k] === 'connected' && ValkeyInstances[k]) {
-      return await ValkeyInstances[k].set(key, value);
-    }
-  } catch (err) {
-    logger.warn('Valkey set failed, writing to dummy', { key, err: err?.message });
-  }
-  if (!DummyStores[k]) DummyStores[k] = new Map();
-  // Store raw string or object accordingly
-  DummyStores[k].set(key, isString ? payload : payload);
-  return 'OK';
+const set = async (options, key, payload, ttlMs) => {
+  const value = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  if (ttlMs) return _client(options).set(key, value, 'PX', ttlMs);
+  return _client(options).set(key, value);
 };
 
 /**
- * Updates an existing object in Valkey by merging it with a new payload.
- * It retrieves the current object, merges it with the new payload, and sets the updated object back.
- * It also updates the `updatedAt` timestamp.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to update.
- * @param {object} [payload={}] - The new data to merge into the object.
- * @returns {Promise<string>} A promise that resolves to the result of the set operation.
+ * Deletes a key.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<number>}
  * @memberof ValkeyService
  */
-const updateValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  let base = await getValkeyObject(options, key);
-  if (typeof base !== 'object' || base === null) base = {};
-  base.updatedAt = new Date().toISOString();
-  return await setValkeyObject(options, key, { ...base, ...payload });
-};
+const del = async (options, key) => _client(options).del(key);
 
 /**
- * Factory function to create a new object based on a model schema.
- * It generates a new object with default properties like `_id`, `createdAt`, and `updatedAt`,
- * and model-specific properties.
- * @param {object} [options={ host: 'localhost', path: '', object: {} }] - Options for object creation.
- * @param {string} [options.host='localhost'] - The host context for the object.
- * @param {object} [options.object={}] - An initial object to extend.
- * @param {string} [model=''] - The name of the model schema to use (e.g., 'user').
- * @returns {Promise<object>} A promise that resolves to the newly created object.
+ * Shallow-merges `payload` into the existing object stored at `key`
+ * and persists the result.  The `updatedAt` timestamp is refreshed automatically.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object} payload
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const valkeyObjectFactory = async (options = { host: 'localhost', path: '', object: {} }, model = '') => {
-  const idoDate = new Date().toISOString();
-  options.object = options.object || {};
-  const { object } = options;
-  const _id = new mongoose.Types.ObjectId().toString();
-  object._id = _id;
-  object.createdAt = idoDate;
-  object.updatedAt = idoDate;
-  switch (model) {
-    case 'user': {
-      const role = 'guest';
-      object._id = `${role}${_id}`;
-      return {
-        ...object,
-        username: `${role}${_id.slice(-5)}`,
-        email: `${_id}@${options.host}`,
-        password: hashPassword(process.env.JWT_SECRET),
-        role,
-        failedLoginAttempts: 0,
-        phoneNumbers: [],
-        publicKey: [],
-        profileImageId: null,
-        emailConfirmed: false,
-        recoverTimeOut: null,
-        lastLoginDate: null,
-        activeSessions: [],
-      };
-    }
-    default:
-      throw new Error(`model schema not found: ${model}`);
-  }
+const update = async (options, key, payload) => {
+  const base = (await get(options, key)) ?? {};
+  return set(options, key, { ...base, ...payload, updatedAt: new Date().toISOString() });
 };
 
+// ─── Public API class ─────────────────────────────────────────────────────────
+
 /**
- * A collection of Valkey-related API functions.
- * @type {object}
- * @memberof ValkeyServiceService
+ * Namespace grouping all Valkey operations.
+ * @memberof ValkeyService
  */
-const ValkeyAPI = {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  createValkeyConnection,
-};
-
-export {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  isValkeyEnable,
-  createValkeyConnection,
-  ValkeyAPI,
-};
+class ValkeyAPI {
+  /** @param {{ host?: string, path?: string }} options */
+  static isConnected = (options) => ValkeyStatus[_instanceKey(options)] === 'connected';
+  static get = get;
+  static set = set;
+  static del = del;
+  static update = update;
+  static createValkeyConnection = createValkeyConnection;
+}
+
+export { isValkeyEnable, createValkeyConnection, get, set, del, update, ValkeyAPI };

package/tsconfig.docs.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "maxNodeModuleJsDepth": 0,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules"]
+}

package/typedoc.json

@@ -0,0 +1,20 @@
+{
+  "name": "Nexodev - ERP, CRM Development & Cloud DevOps Services",
+  "entryPoints": ["./src/server", "./src/api", "./src/db", "./src/ws", "./src/grpc", "./src/mailer", "./src/runtime"],
+  "entryPointStrategy": "expand",
+  "exclude": ["**/node_modules/**", "**/docs/**", "**/client/**"],
+  "out": "./public/www.nexodev.org/docs/",
+  "readme": "./README.md",
+  "tsconfig": "./tsconfig.docs.json",
+  "skipErrorChecking": true,
+  "logLevel": "Error",
+  "includeVersion": true,
+  "hideGenerator": true,
+  "searchInComments": true,
+  "navigation": {
+    "includeCategories": true,
+    "includeGroups": true
+  },
+  "categorizeByGroup": true,
+  "sort": ["source-order"]
+}