underpost 3.0.2 → 3.1.0

package/src/cli/run.js

@@ -4,13 +4,14 @@
  * @namespace UnderpostRun
  */
 
-import { daemonProcess, getTerminalPid, openTerminal, shellCd, shellExec } from '../server/process.js';
+import { daemonProcess, getTerminalPid, shellCd, shellExec } from '../server/process.js';
 import {
   awaitDeployMonitor,
   buildKindPorts,
   Config,
   getNpmRootPath,
   isDeployRunnerContext,
+  loadConfServerJson,
   writeEnv,
 } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
@@ -32,7 +33,6 @@ const logger = loggerFactory(import.meta);
  * @property {string} podName - The name of the pod to run.
  * @property {string} nodeName - The name of the node to run.
  * @property {number} port - Custom port to use.
- * @property {boolean} etcHosts - Whether to modify /etc/hosts.
  * @property {string} volumeHostPath - The host path for the volume.
  * @property {string} volumeMountPath - The mount path for the volume.
  * @property {string} imageName - The name of the image to run.
@@ -56,7 +56,6 @@ const logger = loggerFactory(import.meta);
  * @property {string} apiVersion - The API version for the container.
  * @property {string} claimName - The claim name for the volume.
  * @property {string} kindType - The kind of resource to create.
- * @property {boolean} terminal - Whether to open a terminal.
  * @property {number} devProxyPortOffset - The port offset for the development proxy.
  * @property {boolean} hostNetwork - Whether to use host networking.
  * @property {string} requestsMemory - The memory request for the container.
@@ -85,9 +84,12 @@ const logger = loggerFactory(import.meta);
  * @property {string} monitorStatusKindType - The monitor status kind type option.
  * @property {string} monitorStatusDeltaMs - The monitor status delta in milliseconds.
  * @property {string} monitorStatusMaxAttempts - The maximum number of attempts for monitor status.
+ * @property {boolean} logs - Whether to enable logs.
  * @property {boolean} dryRun - Whether to perform a dry run.
  * @property {boolean} createJobNow - Whether to create the job immediately.
- * @property {boolean} logs - Whether to enable logs.
+ * @property {string|Array<{ip: string, hostnames: string[]}>} hostAliases - Adds entries to the Pod /etc/hosts via Kubernetes hostAliases.
+ *   As a string (CLI): semicolon-separated entries of "ip=hostname1,hostname2" (e.g., "127.0.0.1=foo.local,bar.local;10.1.2.3=foo.remote").
+ *   As an array (programmatic): objects with `ip` and `hostnames` fields (e.g., [{ ip: "127.0.0.1", hostnames: ["foo.local"] }]).
  * @memberof UnderpostRun
  */
 const DEFAULT_OPTION = {
@@ -118,7 +120,6 @@ const DEFAULT_OPTION = {
   apiVersion: '',
   claimName: '',
   kindType: '',
-  terminal: false,
   devProxyPortOffset: 0,
   hostNetwork: false,
   requestsMemory: '',
@@ -150,6 +151,7 @@ const DEFAULT_OPTION = {
   logs: false,
   dryRun: false,
   createJobNow: false,
+  hostAliases: '',
 };
 
 /**
@@ -192,7 +194,7 @@ class UnderpostRun {
       }
 
       {
-        // Detect MongoDB primary pod using centralized method
+        // Detect MongoDB primary pod using method
         let primaryMongoHost = 'mongodb-0.mongodb-service';
         try {
           const primaryPodName = Underpost.db.getMongoPrimaryPodName({
@@ -352,22 +354,35 @@ class UnderpostRun {
     },
     /**
      * @method template-deploy
-     * @description Cleans up, pushes `engine-private` and `engine` repositories with a commit tag `ci package-pwa-microservices-template`.
+     * @description Pushes `engine-private`, dispatches CI workflow to build `pwa-microservices-template`, and optionally dispatches CD sync workflow.
      * @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
      */
     'template-deploy': (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`);
       const message = shellExec(`node bin cmt --changelog --changelog-no-hash`, { silent: true, stdout: true }).trim();
-      shellExec(`${baseCommand} run clean`);
       shellExec(
         `${baseCommand} push ./engine-private ${options.force ? '-f ' : ''}${
           process.env.GITHUB_USERNAME
         }/engine-private`,
       );
       shellCd('/home/dd/engine');
-      shellExec(`git reset`);
+
+      // Store deploy boundary hash for changelog before dispatch
+      const deployBoundaryHash = shellExec('git rev-parse HEAD', {
+        stdout: true,
+        silent: true,
+        disableLog: true,
+      }).trim();
+
       function replaceNthNewline(str, n, replacement = ' ') {
         let count = 0;
         return str.replace(/\r\n?|\n/g, (match) => {
@@ -375,35 +390,54 @@ class UnderpostRun {
           return count === n ? replacement : match;
         });
       }
-      shellExec(
-        `${baseCommand} cmt . --empty ci package-pwa-microservices-template${
-          path.startsWith('sync') ? `-${path}` : ''
-        }${
-          message
-            ? ` "${replaceNthNewline(
-                message.replaceAll('"', '').replaceAll('`', '').replaceAll('#', '').replaceAll('- ', ''),
-                2,
-              )}"`
-            : ''
-        }`,
-      );
+      const sanitizedMessage = message
+        ? replaceNthNewline(message.replaceAll('"', '').replaceAll('`', '').replaceAll('#', '').replaceAll('- ', ''), 2)
+            .replace(/\r\n?|\n/g, ' ')
+            .trim()
+        : '';
+
+      // Push engine repo so workflow YAML changes reach GitHub
+      shellExec(`git reset`);
       shellExec(`${baseCommand} push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`);
+
+      // Dispatch CI workflow instead of empty commit + push
+      const repo = `${process.env.GITHUB_USERNAME}/engine`;
+      Underpost.repo.dispatchWorkflow({
+        repo,
+        workflowFile: 'npmpkg.ci.yml',
+        ref: 'master',
+        inputs: sanitizedMessage ? { message: sanitizedMessage } : {},
+      });
+
+      // Dispatch CD sync-and-deploy if path starts with 'sync'
+      if (path.startsWith('sync')) {
+        const confId = path.replace(/^sync-/, '');
+        Underpost.repo.dispatchWorkflow({
+          repo,
+          workflowFile: `${confId}.cd.yml`,
+          ref: 'master',
+          inputs: { job: 'sync-and-deploy' },
+        });
+      }
+
+      // Store deploy boundary for changelog
+      shellExec(`${baseCommand} config set LAST_CI_DEPLOY_HASH ${deployBoundaryHash}`);
     },
 
     /**
      * @method template-deploy-image
-     * @description Commits and pushes a Docker image deployment for the `engine` repository.
+     * @description Dispatches the Docker image CI workflow for the `engine` repository.
      * @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
      */
     'template-deploy-image': (path, options = DEFAULT_OPTION) => {
-      // const baseCommand = options.dev ? 'node bin' : 'underpost';
-      shellExec(
-        `cd /home/dd/engine && git reset && underpost cmt . --empty ci docker-image 'underpost-engine:${
-          Underpost.version
-        }' && underpost push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`,
-      );
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: 'docker-image.ci.yml',
+        ref: 'master',
+        inputs: {},
+      });
     },
     /**
      * @method clean
@@ -464,18 +498,30 @@ class UnderpostRun {
     },
     /**
      * @method ssh-deploy
-     * @description Performs a Git reset, commits with a message `cd ssh-${path}`, and pushes the `engine` repository, likely triggering an SSH-based CD pipeline.
-     * @param {string} path - The input value, identifier, or path for the operation (used as the deployment identifier for the commit message).
+     * @description Dispatches the corresponding CD workflow for SSH-based deployment, replacing empty commits with workflow_dispatch.
+     * @param {string} path - The deployment identifier (e.g., 'engine-core', 'sync-engine-core', 'init-engine-core').
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
     'ssh-deploy': (path, options = DEFAULT_OPTION) => {
       actionInitLog();
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
-      shellCd('/home/dd/engine');
-      shellExec(`git reset`);
-      shellExec(`${baseCommand} cmt . --empty cd ssh-${path}`);
-      shellExec(`${baseCommand} push . ${options.force ? '-f ' : ''}${process.env.GITHUB_USERNAME}/engine`);
+
+      let job = 'deploy';
+      let confId = path;
+      if (path.startsWith('sync-')) {
+        job = 'sync-and-deploy';
+        confId = path.replace(/^sync-/, '');
+      } else if (path.startsWith('init-')) {
+        job = 'init';
+        confId = path.replace(/^init-/, '');
+      }
+
+      Underpost.repo.dispatchWorkflow({
+        repo: `${process.env.GITHUB_USERNAME}/engine`,
+        workflowFile: `${confId}.cd.yml`,
+        ref: 'master',
+        inputs: { job },
+      });
     },
     /**
      * @method ide
@@ -485,15 +531,25 @@ class UnderpostRun {
      * @param {Object} options - The default underpost runner options for customizing workflow
      * @memberof UnderpostRun
      */
-    ide: (path, options = DEFAULT_OPTION) => {
-      const { underpostRoot } = options;
-      if (path === 'install') {
-        shellExec(`sudo curl -f https://zed.dev/install.sh | sh`);
-        shellExec(
-          `sudo dnf config-manager --add-repo https://download.sublimetext.com/rpm/stable/x86_64/sublime-text.repo`,
-        );
-        shellExec(`sudo dnf install -y sublime-text`);
-      } else shellExec(`node ${underpostRoot}/bin/zed ${path}`);
+    ide: (path = '', options = DEFAULT_OPTION) => {
+      const underpostRoot = options.dev ? '.' : options.underpostRoot;
+      const [projectPath, customIde] = path.split(',');
+      if (projectPath === 'install') {
+        if (customIde === 'zed') shellExec(`sudo curl -f https://zed.dev/install.sh | sh`);
+        else if (customIde === 'subl') {
+          shellExec(
+            `sudo dnf config-manager --add-repo https://download.sublimetext.com/rpm/stable/x86_64/sublime-text.repo`,
+          );
+          shellExec(`sudo dnf install -y sublime-text`);
+        } else {
+          shellExec(`sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc &&
+echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\nautorefresh=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" | sudo tee /etc/yum.repos.d/vscode.repo > /dev/null`);
+          shellExec(`sudo dnf install -y code`);
+        }
+        return;
+      }
+      if (customIde === 'zed') shellExec(`node ${underpostRoot}/bin/zed ${projectPath}`);
+      else shellExec(`node ${underpostRoot}/bin/vs ${projectPath}`);
     },
     /**
      * @method crypto-policy
@@ -522,7 +578,7 @@ class UnderpostRun {
         options.replicas,
         ``,
         ``,
-        options.dev || !isDeployRunnerContext(path, options) ? 'kind-control-plane' : os.hostname(),
+        !options.kubeadm && !options.k3s ? 'kind-control-plane' : os.hostname(),
       ];
       let [deployId, replicas, versions, image, node] = path ? path.split(',') : defaultPath;
       deployId = deployId ? deployId : defaultPath[0];
@@ -1005,9 +1061,7 @@ EOF
         volumeMountPath: volumeHostPath,
         ...(options.dev ? { volumeHostPath } : { claimName }),
         on: {
-          init: async () => {
-            // openTerminal(`kubectl logs -f ${podName}`);
-          },
+          init: async () => {},
         },
         args: [daemonProcess(path ? path : `cd /home/dd/engine && npm install && npm run test`)],
       };
@@ -1142,7 +1196,7 @@ EOF
       const deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',');
       let hosts = [];
       for (const deployId of deployList) {
-        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+        const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
         hosts = hosts.concat(Object.keys(confServer));
       }
       shellExec(`node bin cluster --prom ${hosts.join(',')}`);
@@ -1315,34 +1369,31 @@ EOF
       if (!subConf) subConf = 'local';
       if (options.reset && fs.existsSync(`./engine-private/conf/${deployId}`))
         fs.removeSync(`./engine-private/conf/${deployId}`);
-      if (!fs.existsSync(`./engine-private/conf/${deployId}`)) Config.deployIdFactory(deployId, { subConf });
       if (options.devProxyPortOffset) {
         const envPath = `./engine-private/conf/${deployId}/.env.development`;
         const envObj = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
         envObj.DEV_PROXY_PORT_OFFSET = options.devProxyPortOffset;
         writeEnv(envPath, envObj);
       }
+      dotenv.config({ path: `./engine-private/conf/${deployId}/.env.development`, override: true });
       shellExec(`node bin run dev-cluster --expose --namespace ${options.namespace}`, { async: true });
       {
-        const cmd = `npm run dev-api ${deployId} ${subConf} ${host} ${_path} ${clientHostPort}${
+        const cmd = `npm run dev:api ${deployId} ${subConf} ${host} ${_path} ${clientHostPort} proxy${
           options.tls ? ' tls' : ''
         }`;
-        options.terminal ? openTerminal(cmd) : shellExec(cmd, { async: true });
+        shellExec(cmd, { async: true });
       }
       await awaitDeployMonitor(true);
       {
-        const cmd = `npm run dev-client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
-        options.terminal
-          ? openTerminal(cmd)
-          : shellExec(cmd, {
-              async: true,
-            });
+        const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
+
+        shellExec(cmd, {
+          async: true,
+        });
       }
       await awaitDeployMonitor(true);
       shellExec(
-        `./node_modules/.bin/env-cmd -f .env.development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${
-          options.tls ? ' tls' : ''
-        }`,
+        `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
       );
     },
 
@@ -1361,7 +1412,7 @@ EOF
       let [deployId, serviceId, host, _path, replicas, image, node] = path.split(',');
       if (!replicas) replicas = options.replicas;
       // const confClient = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.client.json`, 'utf8'));
-      const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+      const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
       // const confSSR = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.ssr.json`, 'utf8'));
       // const packageData = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/package.json`, 'utf8'));
       const services = fs.existsSync(`./engine-private/deploy/${deployId}/conf.services.json`)
@@ -1452,9 +1503,7 @@ EOF
     'etc-hosts': async (path = '', options = DEFAULT_OPTION) => {
       const hosts = path ? path.split(',') : [];
       if (options.deployId) {
-        const confServer = JSON.parse(
-          fs.readFileSync(`./engine-private/conf/${options.deployId}/conf.server.json`, 'utf8'),
-        );
+        const confServer = loadConfServerJson(`./engine-private/conf/${options.deployId}/conf.server.json`);
         hosts.push(...Object.keys(confServer));
       }
       const hostListenResult = Underpost.deploy.etcHostFactory(hosts);
@@ -1569,7 +1618,7 @@ EOF
             `npm install -g npm@11.2.0`,
             `npm install -g underpost`,
             `${baseCommand} secret underpost --create-from-file /etc/config/.env.${env}`,
-            `${baseCommand} start --build --run ${deployId} ${env} --underpost-quickly-install`,
+            `${baseCommand} start --build --run ${deployId} ${env}`,
           ];
       shellExec(`node bin run sync${baseClusterCommand} --deploy-id-cron-jobs none dd-test --cmd "${cmd}"`);
     },
@@ -1588,19 +1637,22 @@ EOF
       for (let deployId of fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8').split(',')) {
         deployId = deployId.trim();
         const _path = '/single-replica';
-        const confServer = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.server.json`, 'utf8'));
+        const confServer = loadConfServerJson(`./engine-private/conf/${deployId}/conf.server.json`);
         shellExec(`${baseCommand} env ${deployId} ${env}`);
         for (const host of Object.keys(confServer))
-          if (_path in confServer[host]) shellExec(`node bin/deploy build-single-replica ${deployId} ${host} ${_path}`);
+          if (_path in confServer[host])
+            await Underpost.repo.client(deployId, '', host, _path, {
+              singleReplica: true,
+            });
         const node = options.nodeName
           ? options.nodeName
-          : options.dev || !isDeployRunnerContext(path, options)
+          : !options.kubeadm && !options.k3s
             ? 'kind-control-plane'
             : os.hostname();
         // deployId, replicas, versions, image, node
         let defaultPath = [deployId, 1, ``, ``, node];
         shellExec(`${baseCommand} run${options.dev === true ? ' --dev' : ''} --build sync ${defaultPath}`);
-        shellExec(`node bin/deploy build-full-client ${deployId}`);
+        await Underpost.repo.client(deployId);
       }
       if (isDeployRunnerContext(path, options)) shellExec(`${baseCommand} run promote ${path} production`);
     },
@@ -1677,7 +1729,7 @@ EOF
                   shellExec(`sudo kubectl cp ${nameSpace}/${podName}:${basePath}/docs${fromPath} ${toPath}`);
                 }
 
-                openTerminal(`firefox ${outsPaths.join(' ')}`, { single: true });
+                shellExec(`firefox ${outsPaths.join(' ')}`);
                 process.exit(0);
               }
             })();
@@ -1840,6 +1892,30 @@ EOF
       const imagePullPolicy = options.imagePullPolicy || 'IfNotPresent';
       const hostNetwork = options.hostNetwork ? options.hostNetwork : '';
       const apiVersion = options.apiVersion || 'v1';
+      // Parse hostAliases option:
+      //   - string from CLI: "ip1=host1,host2;ip2=host3,host4"
+      //   - array from programmatic callers: [{ ip: "127.0.0.1", hostnames: ["foo.local"] }]
+      const hostAliases = options.hostAliases
+        ? Array.isArray(options.hostAliases)
+          ? options.hostAliases
+          : options.hostAliases
+              .split(';')
+              .filter((entry) => entry.trim())
+              .map((entry) => {
+                const [ip, hostnamesStr] = entry.split('=');
+                const hostnames = hostnamesStr ? hostnamesStr.split(',').map((h) => h.trim()) : [];
+                return { ip: ip.trim(), hostnames };
+              })
+        : [];
+      const hostAliasesYaml =
+        hostAliases.length > 0
+          ? `  hostAliases:\n${hostAliases
+              .map(
+                (alias) =>
+                  `  - ip: "${alias.ip}"\n    hostnames:\n${alias.hostnames.map((h) => `    - "${h}"`).join('\n')}`,
+              )
+              .join('\n')}`
+          : '';
       const labels = options.labels
         ? options.labels
             .split(',')
@@ -1870,6 +1946,7 @@ spec:
   restartPolicy: ${restartPolicy}
 ${runtimeClassName ? `  runtimeClassName: ${runtimeClassName}` : ''}
 ${hostNetwork ? `  hostNetwork: ${hostNetwork}` : ''}
+${hostAliasesYaml}
   containers:
     - name: ${containerName}
       image: ${imageName}

package/src/cli/secrets.js

@@ -4,13 +4,10 @@
  * @namespace UnderpostSecret
  */
 
-import dotenv from 'dotenv';
 import { shellExec } from '../server/process.js';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
 
-dotenv.config();
-
 /**
  * @class UnderpostSecret
  * @description Manages the secrets of the application.

package/src/cli/ssh.js

@@ -497,7 +497,7 @@ EOF`);
     },
 
     /**
-     * Generic SSH remote command runner that centralizes SSH execution logic.
+     * Generic SSH remote command runner that SSH execution logic.
      * Executes arbitrary shell commands on a remote server via SSH with proper credential handling.
      * @async
      * @function sshRemoteRunner

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

@@ -13,20 +13,32 @@ const AgGrid = {
   Render: async function (options) {
     let { id, paginationOptions } = options;
     setTimeout(() => {
+      // Normalize rowSelection from deprecated string form to object form (AG Grid v32.2.1+)
+      let gridOptionsOverrides = { ...(options.gridOptions || {}) };
+      if (typeof gridOptionsOverrides.rowSelection === 'string') {
+        const mode = gridOptionsOverrides.rowSelection; // 'single' or 'multiple'
+        gridOptionsOverrides.rowSelection = {
+          mode: mode === 'multiple' ? 'multiRow' : 'singleRow',
+        };
+      }
+
       // Grid Options: Contains all of the grid configurations
       const gridOptions = {
+        // Use legacy CSS theme mode to avoid conflict with Theming API (AG Grid v33+)
+        theme: 'legacy',
         // Row Data: The data to be displayed.
         pagination: false, // Disabled by default, will be handled by the management view
         // paginationPageSize: 100,
         // suppressPaginationPanel: true, // We are using our own custom pagination component
         // rowHeight: 60,
-        enableCellChangeFlash: true,
+        // enableCellChangeFlash was removed in v35; use enableCellChangeFlash on defaultColDef instead
         defaultColDef: {
           editable: false,
           flex: 1,
           minWidth: 50,
           filter: true,
           autoHeight: true,
+          enableCellChangeFlash: true,
         },
         rowClassRules: {
           'row-new-highlight': (params) => {
@@ -76,7 +88,7 @@ const AgGrid = {
               return { field };
             })
           : [],
-        ...options.gridOptions,
+        ...gridOptionsOverrides,
       };
 
       // Your Javascript code to create the grid
@@ -86,8 +98,11 @@ const AgGrid = {
       // myGridElement.style.setProperty('width', '100%');
       ThemeEvents[id] = () => {
         if (s(`.${id}`)) {
-          s(`.${id}`).classList.remove(darkTheme ? this.theme : this.theme + '-dark');
-          s(`.${id}`).classList.add(!darkTheme ? this.theme : this.theme + '-dark');
+          // darkTheme has already been updated by Css.js when this event fires
+          // If darkTheme is true: remove light class, add dark class
+          // If darkTheme is false: remove dark class, add light class
+          s(`.${id}`).classList.remove(this.theme, this.theme + '-dark');
+          s(`.${id}`).classList.add(darkTheme ? this.theme + '-dark' : this.theme);
         } else {
           // console.warn('change theme: grid not found');
           delete ThemeEvents[id];
@@ -112,7 +127,7 @@ const AgGrid = {
       : '';
     return html`
       <div
-        class="${id} ${this.theme}${options?.darkTheme ? `-dark` : ''}"
+        class="${id} ${darkTheme ? this.theme + '-dark' : this.theme}"
         style="${options?.style
           ? Object.keys(options.style).map((styleKey) => `${styleKey}: ${options.style[styleKey]}; `)
           : ''}"

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

@@ -56,7 +56,7 @@ const attachMarkdownLinkHandlers = (containerSelector) => {
 };
 
 const Content = {
-  Render: async function (options = { idModal: '' }) {
+  Render: async function (options = { idModal: '', titleIcon: '' }) {
     const { idModal } = options;
     setTimeout(async () => {
       try {
@@ -111,11 +111,30 @@ const Content = {
           throw new Error(`no-preview-available`);
         }
 
+        // Use custom titleIcon from options, or extract from the modal's original title HTML, or fall back to default
+        const titleIcon = options.titleIcon
+          ? options.titleIcon
+          : Modal.Data[idModal] &&
+              Modal.Data[idModal].options &&
+              Modal.Data[idModal].options.title &&
+              Modal.Data[idModal].options.title.includes &&
+              Modal.Data[idModal].options.title.includes('<img')
+            ? Modal.Data[idModal].options.title.match(/<img[^>]*>/)?.[0] || html`<i class="inl far fa-file"></i>`
+            : html`<i class="inl far fa-file"></i>`;
+
+        // Preserve the original text wrapper class if present in the modal's stored title
+        const originalTitle = Modal.Data[idModal]?.options?.title || '';
+        const hasCustomTextClass = originalTitle.includes && originalTitle.includes('underpost-text-title-modal');
+        const docTitle = documentObj.title ? documentObj.title : documentObj.location;
+        const titleText = hasCustomTextClass
+          ? `<span class='inl underpost-text-title-modal'>${docTitle}</span>`
+          : docTitle;
+
         htmls(
           `.title-modal-${idModal}`,
           html`${renderViewTitle({
-            icon: html`<i class="inl far fa-file"></i>`,
-            text: `${documentObj.title ? documentObj.title : documentObj.location}`,
+            icon: titleIcon,
+            text: titleText,
           })} `,
         );
         htmls(`.content-render-${idModal}`, ``);

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

@@ -12,6 +12,10 @@ const Docs = {
     const docData = this.Data.find((d) => d.type === type);
     const ModalId = `modal-docs-${docData.type}`;
     const { barConfig } = await Themes[Css.currentTheme]();
+    const parentBarMode =
+      Modal.Data['modal-docs'] && Modal.Data['modal-docs'].options.barMode
+        ? Modal.Data['modal-docs'].options.barMode
+        : undefined;
 
     await Modal.Render({
       barConfig,
@@ -34,7 +38,7 @@ const Docs = {
       route: 'docs',
       slideMenu: 'modal-menu',
       observer: true,
-      barMode: 'top-bottom-bar',
+      barMode: parentBarMode,
       query: true,
       RouterInstance: Modal.Data['modal-docs'].options.RouterInstance,
     });
@@ -166,6 +170,8 @@ const Docs = {
       icon: html`<i class="fab fa-github"></i>`,
       text: `Last Release`,
       url: function () {
+        const tokenOpts = Docs.Tokens['modal-docs'];
+        if (tokenOpts && tokenOpts.lastReleaseUrl) return tokenOpts.lastReleaseUrl();
         return `https://github.com/underpostnet/pwa-microservices-template-ghpkg/`;
       },
     },
@@ -180,6 +186,8 @@ const Docs = {
       </svg>`,
       text: html`Demo`,
       url: function () {
+        const tokenOpts = Docs.Tokens['modal-docs'];
+        if (tokenOpts && tokenOpts.demoUrl) return tokenOpts.demoUrl();
         return `https://underpostnet.github.io/pwa-microservices-template-ghpkg/`;
       },
     },
@@ -204,6 +212,8 @@ const Docs = {
       icon: html`<img height="20" width="20" class="doc-icon-coverage" />`,
       text: `Coverage report`,
       url: function () {
+        const tokenOpts = Docs.Tokens['modal-docs'];
+        if (tokenOpts && tokenOpts.coverageUrl) return tokenOpts.coverageUrl();
         return `${getProxyPath()}docs/coverage`;
       },
       themeEvent: () => {
@@ -223,7 +233,7 @@ const Docs = {
     },
   ],
   Tokens: {},
-  Init: async function (options) {
+  Init: async function (options = {}) {
     const { idModal } = options;
     this.Tokens[idModal] = options;
     setTimeout(() => {
@@ -284,10 +294,14 @@ const Docs = {
           break;
       }
       tabHref = docData.url();
+      const subMenuIcon =
+        options.subMenuIcon && typeof options.subMenuIcon === 'function'
+          ? options.subMenuIcon(docData.type)
+          : docData.icon;
       docMenuRender += html`
         ${await BtnIcon.Render({
           class: `in wfa main-btn-menu submenu-btn btn-docs btn-docs-${docData.type}`,
-          label: html`<span class="inl menu-btn-icon">${docData.icon}</span
+          label: html`<span class="inl menu-btn-icon">${subMenuIcon}</span
             ><span class="menu-label-text menu-label-text-docs"> ${docData.text} </span>`,
           tabHref,
           tooltipHtml: await Badge.Render(buildBadgeToolTipMenuOption(docData.text, 'right')),
@@ -447,7 +461,10 @@ const Docs = {
                   if (s(`.docs-card-container-${item.id}`)) {
                     s(`.docs-card-container-${item.id}`).onclick = () => {
                       if (item.id.match('demo')) {
-                        location.href = 'https://underpostnet.github.io/pwa-microservices-template-ghpkg/';
+                        const demoData = Docs.Data.find((d) => d.type === 'demo');
+                        location.href = demoData
+                          ? demoData.url()
+                          : 'https://underpostnet.github.io/pwa-microservices-template-ghpkg/';
                       } else if (item.id.match('api')) {
                         if (s(`.btn-docs-api`)) s(`.btn-docs-api`).click();
                       } else {