underpost 3.1.3 → 3.2.2

package/src/cli/run.js

@@ -4,7 +4,8 @@
  * @namespace UnderpostRun
  */
 
-import { daemonProcess, getTerminalPid, shellCd, shellExec } from '../server/process.js';
+import { daemonProcess, getTerminalPid, pbcopy, shellCd, shellExec } from '../server/process.js';
+import crypto from 'crypto';
 import {
   awaitDeployMonitor,
   buildKindPorts,
@@ -17,12 +18,31 @@ import {
 import { actionInitLog, loggerFactory } from '../server/logger.js';
 
 import fs from 'fs-extra';
+import net from 'net';
 import { range, setPad, timer } from '../client/components/core/CommonJs.js';
 
 import os from 'os';
 import Underpost from '../index.js';
 import dotenv from 'dotenv';
 
+const waitForPort = (port, host = '127.0.0.1', { maxAttempts = 30, interval = 2000 } = {}) =>
+  new Promise((resolve, reject) => {
+    let attempts = 0;
+    const tryConnect = () => {
+      attempts++;
+      const socket = net.createConnection({ port, host }, () => {
+        socket.destroy();
+        resolve();
+      });
+      socket.on('error', () => {
+        socket.destroy();
+        if (attempts >= maxAttempts) return reject(new Error(`Port ${port} not ready after ${maxAttempts} attempts`));
+        setTimeout(tryConnect, interval);
+      });
+    };
+    tryConnect();
+  });
+
 const logger = loggerFactory(import.meta);
 
 /**
@@ -154,6 +174,8 @@ const DEFAULT_OPTION = {
   createJobNow: false,
   fromNCommit: 0,
   hostAliases: '',
+  gitClean: false,
+  copy: false,
 };
 
 /**
@@ -246,8 +268,15 @@ class UnderpostRun {
       const ports = '6379,27017';
       shellExec(`node bin run kill '${ports}'`);
       shellExec(`node bin run dev-cluster --dev --expose --namespace ${options.namespace}`, { async: true });
-      console.log('Loading fordward services...');
-      await timer(5000);
+      logger.info('Waiting for port-forward services to be ready...');
+      try {
+        await Promise.all([waitForPort(27017), waitForPort(6379)]);
+        logger.info('Port-forward services are ready');
+      } catch (err) {
+        logger.error('Port-forward services failed to become ready', { error: err.message });
+        shellExec(`node bin run kill '${ports}'`);
+        throw err;
+      }
       shellExec(`node bin metadata --generate ${path}`);
       shellExec(`node bin db --dev --clean-fs-collection dd`);
       shellExec(`node bin run kill '${ports}'`);
@@ -373,8 +402,12 @@ class UnderpostRun {
       }
       shellExec(`${baseCommand} run pull`);
 
-      // Capture last N commit messages for propagation (default: last 1 commit)
-      const fromN = options.fromNCommit && parseInt(options.fromNCommit) > 0 ? parseInt(options.fromNCommit) : 1;
+      // Capture last N commit messages for propagation.
+      // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
+      const fromN =
+        options.fromNCommit && parseInt(options.fromNCommit) > 0
+          ? parseInt(options.fromNCommit)
+          : Underpost.repo.getUnpushedCount('.').count;
       const message = shellExec(`node bin cmt --changelog ${fromN} --changelog-no-hash`, {
         silent: true,
         stdout: true,
@@ -423,6 +456,40 @@ class UnderpostRun {
       });
     },
 
+    /**
+     * @method template-deploy-local
+     * @description Similar to `template-deploy` but runs the workflow locally without dispatching GitHub Actions. It pulls the latest changes, pushes to GitHub, builds the template, and optionally triggers a local release with CI push.
+     * @param {string} path - The deployment path identifier (e.g., 'sync-engine-core', 'init-engine-core', or empty for build-only).
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'template-deploy-local': async (path, options = DEFAULT_OPTION) => {
+      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      shellExec(`npm run security:secrets`);
+      const reportPath = './gitleaks-report.json';
+      if (fs.existsSync(reportPath) && JSON.parse(fs.readFileSync(reportPath, 'utf8')).length > 0) {
+        logger.error('Secrets detected in gitleaks-report.json, aborting template-deploy');
+        return;
+      }
+      shellExec(`${baseCommand} run pull`);
+
+      // Capture last N commit messages from the engine repo.
+      // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
+      const fromN =
+        options.fromNCommit && parseInt(options.fromNCommit) > 0
+          ? parseInt(options.fromNCommit)
+          : Underpost.repo.getUnpushedCount('.').count;
+      const rawMessage = shellExec(`node bin cmt --changelog ${fromN} --changelog-no-hash`, {
+        silent: true,
+        stdout: true,
+      }).trim();
+      const sanitizedMessage = Underpost.repo.sanitizeChangelogMessage(rawMessage);
+
+      const { triggerCmd } = path
+        ? await Underpost.release.ci(path, sanitizedMessage, options)
+        : await Underpost.release.pwa(sanitizedMessage, options);
+      pbcopy(triggerCmd + ' && cd /home/dd/engine');
+    },
     /**
      * @method template-deploy-image
      * @description Dispatches the Docker image CI workflow for the `engine` repository.
@@ -438,6 +505,21 @@ class UnderpostRun {
         inputs: {},
       });
     },
+    /**
+     * @method docker-image
+     * @description Dispatches the Docker image CI workflow (`docker-image.ci.yml`) for the `engine` repository via `workflow_dispatch`.
+     * @param {string} path - The input value, identifier, or path for the operation.
+     * @param {Object} options - The default underpost runner options for customizing workflow
+     * @memberof UnderpostRun
+     */
+    'docker-image': (path, options = DEFAULT_OPTION) => {
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: 'docker-image.ci.yml',
+        ref: 'master',
+        inputs: {},
+      });
+    },
     /**
      * @method clean
      * @description Changes directory to the provided path (defaulting to `/home/dd/engine`) and runs `node bin/deploy clean-core-repo`.
@@ -605,20 +687,22 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       const cmdString = options.cmd
         ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
         : '';
+      const clusterFlag = options.k3s ? ' --k3s' : options.kind ? ' --kind' : ' --kubeadm';
+      const gitCleanFlag = options.gitClean ? ' --git-clean' : '';
 
       shellExec(
-        `${baseCommand} deploy --kubeadm --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
+        `${baseCommand} deploy${clusterFlag} --build-manifest --sync --info-router --replicas ${replicas} --node ${node}${
           image ? ` --image ${image}` : ''
         }${versions ? ` --versions ${versions}` : ''}${
           options.namespace ? ` --namespace ${options.namespace}` : ''
-        }${timeoutFlags}${cmdString} ${deployId} ${env}`,
+        }${timeoutFlags}${cmdString}${gitCleanFlag} ${deployId} ${env}`,
       );
 
       if (isDeployRunnerContext(path, options)) {
         shellExec(
-          `${baseCommand} deploy --kubeadm${cmdString} --replicas ${replicas} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
+          `${baseCommand} deploy${clusterFlag}${cmdString} --replicas ${replicas} --disable-update-proxy ${deployId} ${env} --versions ${versions}${
             options.namespace ? ` --namespace ${options.namespace}` : ''
-          }${timeoutFlags}`,
+          }${timeoutFlags}${gitCleanFlag}`,
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
@@ -830,6 +914,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       const confInstances = JSON.parse(
         fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'),
       );
+      let promotedTraffic = '';
       for (const instance of confInstances) {
         let {
           id: _id,
@@ -849,6 +934,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
           namespace: options.namespace,
         });
         const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
+        promotedTraffic = targetTraffic;
         let proxyYaml =
           Underpost.deploy.baseProxyYamlFactory({ host: _host, env: options.tls ? 'production' : env, options }) +
           Underpost.deploy.deploymentYamlServiceFactory({
@@ -874,6 +960,18 @@ EOF
           { disableLog: true },
         );
       }
+      // Refresh the gRPC service to ensure it points to the parent deploy's current traffic.
+      if (promotedTraffic) {
+        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
+          deployId,
+          env,
+          confServer: loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
+          namespace: options.namespace,
+          traffic: [parentTraffic],
+        });
+        if (grpcServicePath) shellExec(`kubectl apply -f ${grpcServicePath} -n ${options.namespace}`);
+      }
     },
 
     /**
@@ -913,12 +1011,12 @@ EOF
         // `localhost/rockylinux9-underpost:${Underpost.version}`
         if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
 
-        if (options.nodeName) {
-          shellExec(`sudo crictl pull ${_image}`);
-        } else {
-          shellExec(`docker pull ${_image}`);
-          shellExec(`sudo kind load docker-image ${_image}`);
-        }
+        Underpost.image.pullDockerHubImage({
+          dockerhubImage: _image,
+          kind: options.kind || (!options.nodeName && !options.kubeadm && !options.k3s),
+          kubeadm: options.nodeName || options.kubeadm,
+          k3s: options.k3s,
+        });
 
         const currentTraffic = Underpost.deploy.getCurrentTraffic(_deployId, {
           hostTest: _host,
@@ -927,7 +1025,7 @@ EOF
 
         const targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'blue';
         const podId = `${_deployId}-${env}-${targetTraffic}`;
-        const ignorePods = Underpost.deploy.get(podId, 'pods', options.namespace).map((p) => p.NAME);
+        const ignorePods = Underpost.kubectl.get(podId, 'pods', options.namespace).map((p) => p.NAME);
         Underpost.deploy.configMap(env, options.namespace);
         shellExec(`kubectl delete service ${podId}-service --namespace ${options.namespace} --ignore-not-found`);
         shellExec(`kubectl delete deployment ${podId} --namespace ${options.namespace} --ignore-not-found`);
@@ -939,7 +1037,30 @@ EOF
               env,
               version: targetTraffic,
               nodeName: options.nodeName,
+              clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
+              gitClean: options.gitClean || false,
             });
+        // Regenerate the parent deploy's gRPC ClusterIP service pointing to the
+        // parent's current traffic colour and apply it before the instance pod starts so
+        // DNS is resolvable the moment the pod boots.
+        const parentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }) || 'blue';
+        const grpcServicePath = Underpost.deploy.buildGrpcServiceManifest({
+          deployId,
+          env,
+          confServer: loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`),
+          namespace: options.namespace,
+          traffic: [targetTraffic],
+          host: _host,
+        });
+        if (grpcServicePath) shellExec(`kubectl apply -f ${grpcServicePath} -n ${options.namespace}`);
+
+        const resolvedCmd = _cmd[env].map((c) =>
+          c.replaceAll(
+            '{{grpc-service-dns}}',
+            `${deployId}-grpc-service-${env}-${parentTraffic}.${options.namespace || 'default'}.svc.cluster.local:50051`,
+          ),
+        );
+
         let deploymentYaml = `---
 ${Underpost.deploy
   .deploymentYamlPartsFactory({
@@ -951,7 +1072,7 @@ ${Underpost.deploy
     image: _image,
     namespace: options.namespace,
     volumes: _volumes,
-    cmd: _cmd[env],
+    cmd: resolvedCmd,
   })
   .replace('{{ports}}', buildKindPorts(_fromPort, _toPort))}
 `;
@@ -997,7 +1118,7 @@ EOF
      * @memberof UnderpostRun
      */
     'ls-deployments': async (path, options = DEFAULT_OPTION) => {
-      console.table(await Underpost.deploy.get(path, 'deployments', options.namespace));
+      console.table(await Underpost.kubectl.get(path, 'deployments', options.namespace));
     },
 
     /**
@@ -1091,15 +1212,13 @@ EOF
     'db-client': async (path, options = DEFAULT_OPTION) => {
       const { underpostRoot } = options;
 
-      const image = 'adminer:4.7.6-standalone';
-
-      if (!options.kubeadm && !options.k3s) {
-        // Only load if not kubeadm/k3s (Kind needs it)
-        shellExec(`docker pull ${image}`);
-        shellExec(`sudo kind load docker-image ${image}`);
-      } else if (options.kubeadm || options.k3s)
-        // For kubeadm/k3s, ensure it's available for containerd
-        shellExec(`sudo crictl pull ${image}`);
+      Underpost.image.pullDockerHubImage({
+        dockerhubImage: 'adminer',
+        version: '4.7.6-standalone',
+        kind: options.kind,
+        kubeadm: options.kubeadm,
+        k3s: options.k3s,
+      });
 
       shellExec(`kubectl delete deployment adminer -n ${options.namespace} --ignore-not-found`);
       shellExec(`kubectl apply -k ${underpostRoot}/manifests/deployment/adminer/. -n ${options.namespace}`);
@@ -1662,7 +1781,7 @@ EOF
         : [
             `npm install -g npm@11.2.0`,
             `npm install -g underpost`,
-            `${baseCommand} secret underpost --create-from-file /etc/config/.env.${env}`,
+            `${baseCommand} secret underpost --create-from-env`,
             `${baseCommand} start --build --run ${deployId} ${env}`,
           ];
       shellExec(`node bin run sync${baseClusterCommand} --deploy-id-cron-jobs none dd-test --cmd "${cmd}"`);
@@ -1693,7 +1812,7 @@ EOF
 
               const { close } = await (async () => {
                 const checkAwaitPath = '/await';
-                while (!Underpost.deploy.existsContainerFile({ podName, path: checkAwaitPath })) {
+                while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
                   logger.info('monitor', checkAwaitPath);
                   await timer(1000);
                 }
@@ -1720,7 +1839,7 @@ EOF
                 logger.info('monitor', checkPath);
                 {
                   const checkAwaitPath = `/home/dd/docs${checkPath}`;
-                  while (!Underpost.deploy.existsContainerFile({ podName, path: checkAwaitPath })) {
+                  while (!Underpost.kubectl.existsFile({ podName, path: checkAwaitPath })) {
                     logger.info('waiting for', checkAwaitPath);
                     await timer(1000);
                   }
@@ -1786,7 +1905,8 @@ EOF
 
       shellCd(dir);
 
-      shellExec(`git init && git add . && git commit -m "Base implementation"`);
+      Underpost.repo.initLocalRepo({ path: dir });
+      shellExec(`git add . && git commit -m "Base implementation"`);
       shellExec(`chmod +x ./replace_params.sh`);
       shellExec(`chmod +x ./build.sh`);
 
@@ -1831,11 +1951,46 @@ EOF
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
+    /**
+     * @method generate-pass
+     * @description Generates a cryptographically secure random password that satisfies all validatePassword
+     * constraints (lowercase, uppercase, digit, special char, min 8 chars). Logs the plain password
+     * to the console or, when `--copy` is set, copies it to the clipboard via pbcopy.
+     * @param {string} path - Optional password length (default: 16).
+     * @param {Object} options - The default underpost runner options for customizing workflow.
+     * @param {boolean} options.copy - When true, copies to clipboard instead of logging.
+     * @memberof UnderpostRun
+     */
+    'generate-pass': (path, options = DEFAULT_OPTION) => {
+      const length = path && parseInt(path) > 0 ? parseInt(path) : 16;
+      const lower = 'abcdefghijklmnopqrstuvwxyz';
+      const upper = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+      const digits = '0123456789';
+      const special = '@#$%^&*()_+';
+      const all = lower + upper + digits + special;
+      const buf = crypto.randomBytes(length + 4);
+      // Guarantee at least one character from each required class
+      const chars = [
+        lower[buf[0] % lower.length],
+        upper[buf[1] % upper.length],
+        digits[buf[2] % digits.length],
+        special[buf[3] % special.length],
+      ];
+      for (let i = 4; i < length; i++) chars.push(all[buf[i] % all.length]);
+      // Fisher-Yates shuffle using an independent random buffer
+      const shuf = crypto.randomBytes(length);
+      for (let i = chars.length - 1; i > 0; i--) {
+        const j = shuf[i % shuf.length] % (i + 1);
+        [chars[i], chars[j]] = [chars[j], chars[i]];
+      }
+      const password = chars.join('');
+      if (options.copy) pbcopy(password);
+      else console.log(password);
+    },
+
     secret: (path, options = DEFAULT_OPTION) => {
       const secretPath = path ? path : `/home/dd/engine/engine-private/conf/dd-cron/.env.production`;
-      const command = options.dev
-        ? `node bin secret underpost --create-from-file ${secretPath}`
-        : `underpost secret underpost --create-from-file ${secretPath}`;
+      const command = `node bin secret underpost --create-from-file ${secretPath}`;
       shellExec(command);
     },
     /**

package/src/cli/secrets.js

@@ -8,6 +8,10 @@ import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
 import dotenv from 'dotenv';
 import Underpost from '../index.js';
+import { loadConf } from '../server/conf.js';
+import { loggerFactory } from '../server/logger.js';
+
+const logger = loggerFactory(import.meta);
 
 /**
  * @class UnderpostSecret
@@ -23,11 +27,80 @@ class UnderpostSecret {
      */
     underpost: {
       createFromEnvFile(envPath) {
+        Underpost.env.clean();
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
         for (const key of Object.keys(envObj)) {
           Underpost.env.set(key, envObj[key]);
         }
       },
+      /** Reads application secrets from process.env (injected via envFrom: secretRef)
+       *  and writes them to the underpost .env file, filtering out known system and
+       *  Kubernetes-injected environment variables. Replaces the fragile shell-based
+       *  `printenv | grep -vE` pattern with a maintainable Node.js blocklist.
+       */
+      createFromContainerEnv() {
+        Underpost.env.clean();
+        const systemKeys = new Set([
+          'HOME',
+          'HOSTNAME',
+          'PATH',
+          'TERM',
+          'SHLVL',
+          'PWD',
+          '_',
+          'LANG',
+          'LANGUAGE',
+          'LC_ALL',
+          'container',
+          'SHELL',
+          'USER',
+          'LOGNAME',
+          'MAIL',
+          'OLDPWD',
+          'LESSOPEN',
+          'LESSCLOSE',
+          'LS_COLORS',
+          'DISPLAY',
+          'COLORTERM',
+          'EDITOR',
+          'VISUAL',
+          'TERM_PROGRAM',
+          'TERM_PROGRAM_VERSION',
+          'SSH_AUTH_SOCK',
+          'SSH_CLIENT',
+          'SSH_CONNECTION',
+          'SSH_TTY',
+          'XDG_SESSION_ID',
+          'XDG_RUNTIME_DIR',
+          'XDG_DATA_DIRS',
+          'XDG_CONFIG_DIRS',
+          'DBUS_SESSION_BUS_ADDRESS',
+          'GPG_AGENT_INFO',
+          'WINDOWID',
+          'DESKTOP_SESSION',
+          'SESSION_MANAGER',
+          'XAUTHORITY',
+          'WAYLAND_DISPLAY',
+          'which_declare',
+        ]);
+        const systemKeyPrefixes = ['KUBERNETES_', 'npm_', 'NODE_'];
+        for (const [key, value] of Object.entries(process.env)) {
+          if (systemKeys.has(key)) continue;
+          if (systemKeyPrefixes.some((prefix) => key.startsWith(prefix))) continue;
+          Underpost.env.set(key, value);
+        }
+      },
+    },
+
+    /**
+     * Removes all filesystem traces of secrets after deployment startup.
+     * Centralizes the defense-in-depth cleanup performed
+     * @memberof UnderpostSecret
+     */
+    globalSecretClean() {
+      loadConf('clean');
+      Underpost.repo.cleanupPrivateEngineRepo();
+      Underpost.env.clean();
     },
   };
 }

package/src/cli/test.js

@@ -81,7 +81,7 @@ class UnderpostTest {
         return await Underpost.test.statusMonitor(options.podName, options.podStatus, options.kindType);
 
       if (options.sh === true || options.logs === true) {
-        const [pod] = Underpost.deploy.get(deployList);
+        const [pod] = Underpost.kubectl.get(deployList);
         if (pod) {
           if (options.sh) return pbcopy(`sudo kubectl exec -it ${pod.NAME} -- sh`);
           if (options.logs) return shellExec(`sudo kubectl logs -f ${pod.NAME}`);
@@ -115,7 +115,7 @@ class UnderpostTest {
                 break;
             }
           else {
-            const pods = Underpost.deploy.get(deployId);
+            const pods = Underpost.kubectl.get(deployId);
             if (pods.length > 0)
               for (const deployData of pods) {
                 const { NAME } = deployData;
@@ -145,7 +145,7 @@ class UnderpostTest {
         logger.info(`Loading instance`, { podName, status, kindType, deltaMs, maxAttempts });
         const _monitor = async () => {
           await timer(deltaMs);
-          const pods = Underpost.deploy.get(podName, kindType);
+          const pods = Underpost.kubectl.get(podName, kindType);
           let result = pods.find((p) => p.STATUS === status || (status === 'Running' && p.STATUS === 'Completed'));
           logger.info(
             `Testing pod ${podName}... ${result ? 1 : 0}/1 - elapsed time ${deltaMs * (index + 1)}s - attempt ${

package/src/client/Default.index.js

@@ -11,10 +11,9 @@ import { RouterDefault } from './components/default/RoutesDefault.js';
 import { TranslateDefault } from './components/default/TranslateDefault.js';
 import { Worker } from './components/core/Worker.js';
 import { Keyboard } from './components/core/Keyboard.js';
-import { DefaultParams } from './components/default/CommonDefault.js';
 import { SocketIo } from './components/core/SocketIo.js';
 import { SocketIoDefault } from './components/default/SocketIoDefault.js';
-import { ElementsDefault } from './components/default/ElementsDefault.js';
+import { AppStoreDefault } from './components/default/AppStoreDefault.js';
 import { CssDefaultDark, CssDefaultLight } from './components/default/CssDefault.js';
 import { EventsUI } from './components/core/EventsUI.js';
 import { Modal } from './components/core/Modal.js';
@@ -71,14 +70,14 @@ window.onload = () =>
       await Responsive.Init();
       await MenuDefault.Render({ htmlMainBody });
       await SocketIo.Init({
-        channels: ElementsDefault.Data,
+        channels: AppStoreDefault.Data,
         path: `/`,
       });
       await SocketIoDefault.Init();
       await LogInDefault();
       await LogOutDefault();
       await SignUpDefault();
-      await Keyboard.Init({ callBackTime: DefaultParams.EVENT_CALLBACK_TIME });
+      await Keyboard.Init();
       await Modal.RenderSeoSanitizer();
     },
   });

package/src/client/components/core/AppStore.js

@@ -0,0 +1,69 @@
+/**
+ * Core per-app state store for WebSocket channel data.
+ *
+ * @module client/core/AppStore
+ * @namespace AppStore
+ */
+
+/**
+ * @class AppStore
+ * @classdesc Per-app singleton state store for WebSocket channel data and authenticated user state.
+ *
+ * Usage: `AppStoreX.Data.user.main.model.user` — the authenticated user object.
+ * `AppStoreX.Data` keys (`chat`, `mailer`, `stream`, etc.) — channel definitions for `SocketIo.Init`.
+ * @memberof AppStore
+ */
+class AppStore {
+  /**
+   * Channel data map, keyed by channel name (e.g. `user`, `chat`, `mailer`).
+   * The `user` channel always contains `{ main: { model: { user: { _id: '' } } } }`.
+   *
+   * @type {Object.<string, Object>}
+   */
+  Data;
+
+  /** @private @type {function(): Object} */
+  #initialStateFactory;
+
+  /**
+   * Creates a new AppStore instance.
+   *
+   * @param {function(): Object} initialStateFactory - Factory function returning the initial data shape.
+   *   Must return at least `{ user: { main: { model: { user: { _id: '' } } } } }`.
+   */
+  constructor(initialStateFactory) {
+    this.#initialStateFactory = initialStateFactory;
+    this.Data = initialStateFactory();
+  }
+
+  /**
+   * Resets `Data` to its initial state.
+   *
+   * @returns {void}
+   */
+  reset() {
+    this.Data = this.#initialStateFactory();
+  }
+
+  /**
+   * Creates an AppStore with the standard channel layout.
+   * Always includes `user`, `chat`, and `mailer` channels.
+   *
+   * @static
+   * @param {...string} extraChannels - Additional channel names (e.g. `'stream'`).
+   * @returns {AppStore}
+   */
+  static create(...extraChannels) {
+    return new AppStore(() => {
+      const state = {
+        user: { main: { model: { user: { _id: '' } } } },
+        chat: {},
+        mailer: {},
+      };
+      for (const ch of extraChannels) state[ch] = {};
+      return state;
+    });
+  }
+}
+
+export { AppStore };

package/src/client/components/core/CalendarCore.js

@@ -25,7 +25,7 @@ const eventDateFactory = (event) =>
 const CalendarCore = {
   RenderStyle: async function () {},
   Data: {},
-  Render: async function (options = { idModal: '', Elements: {}, hiddenDates: [] }) {
+  Render: async function (options = { idModal: '', appStore: {}, hiddenDates: [] }) {
     this.Data[options.idModal] = {
       data: [],
       originData: [],
@@ -49,7 +49,7 @@ const CalendarCore = {
         this.Data[options.idModal].filesData = [];
         this.Data[options.idModal].originData = newInstance(resultData);
         this.Data[options.idModal].data = resultData.map((o) => {
-          if (o.creatorUserId && options.Elements.Data.user.main.model.user._id === o.creatorUserId) o.tools = true;
+          if (o.creatorUserId && options.appStore.Data.user.main.model.user._id === o.creatorUserId) o.tools = true;
           o.id = o._id;
 
           this.Data[options.idModal].filesData.push({});