underpost 3.2.5 → 3.2.8

package/src/api/user/user.controller.js

@@ -25,11 +25,11 @@ const handleRequest = (serviceMethod) => async (req, res, options) => {
   }
 };
 
-const UserController = {
-  post: handleRequest(UserService.post),
-  get: handleRequest(UserService.get),
-  delete: handleRequest(UserService.delete),
-  put: handleRequest(UserService.put),
-};
+class UserController {
+  static post = handleRequest(UserService.post);
+  static get = handleRequest(UserService.get);
+  static delete = handleRequest(UserService.delete);
+  static put = handleRequest(UserService.put);
+}
 
 export { UserController };

package/src/api/user/user.model.js

@@ -3,7 +3,6 @@ import validator from 'validator';
 import { userRoleEnum } from '../../client/components/core/CommonJs.js';
 import crypto from 'crypto';
 // https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
-
 const UserSchema = new Schema(
   {
     email: {
@@ -88,13 +87,10 @@ const UserSchema = new Schema(
     timestamps: true,
   },
 );
-
 const UserModel = model('User', UserSchema);
-
 const ProviderSchema = UserSchema;
-
-const UserDto = {
-  select: {
+class UserDto {
+  static select = {
     get: () => {
       return {
         _id: 1,
@@ -112,8 +108,8 @@ const UserDto = {
     getAll: () => {
       return { _id: 1 };
     },
-  },
-  public: {
+  };
+  static public = {
     get: () => {
       return {
         _id: 1,
@@ -125,8 +121,8 @@ const UserDto = {
         updatedAt: 1,
       };
     },
-  },
-  auth: {
+  };
+  static auth = {
     payload: (user, jwtid, ip, userAgent, host, path) => {
       const tokenPayload = {
         _id: user._id.toString(),
@@ -141,7 +137,6 @@ const UserDto = {
       };
       return tokenPayload;
     },
-  },
-};
-
+  };
+}
 export { UserSchema, UserModel, userRoleEnum, ProviderSchema, UserDto };

package/src/api/user/user.service.js

@@ -9,7 +9,6 @@ import {
   refreshSessionAndToken,
   logoutSession,
   jwtSign,
-  getBearerToken,
   validatePasswordMiddleware,
 } from '../../server/auth.js';
 import { MailerProvider } from '../../mailer/MailerProvider.js';
@@ -19,8 +18,8 @@ import validator from 'validator';
 import { DataBaseProvider } from '../../db/DataBaseProvider.js';
 import { FileFactory, FileCleanup } from '../file/file.service.js';
 import { UserDto } from './user.model.js';
-import { selectDtoFactory, ValkeyAPI } from '../../server/valkey.js';
 import { timer } from '../../client/components/core/CommonJs.js';
+import { GuestService } from './guest.service.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -226,15 +225,7 @@ const UserService = {
         } else throw new Error('Invalid credentials');
 
       case 'guest': {
-        const user = await ValkeyAPI.valkeyObjectFactory(options, 'user');
-        await ValkeyAPI.setValkeyObject(options, user.email, user);
-        return {
-          token: jwtSign(
-            UserDto.auth.payload(user, null, req.ip, req.headers['user-agent'], options.host, options.path),
-            options,
-          ),
-          user: selectDtoFactory(user, UserDto.select.get()),
-        };
+        return await GuestService.create(req, options);
       }
 
       default:
@@ -360,8 +351,7 @@ const UserService = {
       case 'auth': {
         let user;
         if (req.auth.user._id.match('guest')) {
-          user = await ValkeyAPI.getValkeyObject(options, req.auth.user.email);
-          if (!user) throw new Error('guest user expired');
+          return await GuestService.auth(req, options);
         } else
           user = await User.findOne({
             _id: req.auth.user._id,
@@ -369,13 +359,6 @@ const UserService = {
 
         if (!user) throw new Error('user not found');
 
-        const guestUser = await ValkeyAPI.getValkeyObject(options, req.auth.user.email);
-        if (guestUser)
-          return {
-            user: selectDtoFactory(guestUser, UserDto.select.get()),
-            token: getBearerToken(req),
-          };
-
         return {
           token: await refreshSessionAndToken(req, res, User, options),
           user: await User.findOne({

package/src/cli/deploy.js

@@ -9,6 +9,7 @@ import {
   buildPortProxyRouter,
   buildProxyRouter,
   Config,
+  cronDeployIdResolve,
   deployRangePortFactory,
   getDataDeploy,
   loadConfServerJson,
@@ -130,8 +131,8 @@ class UnderpostDeploy {
     deploymentYamlPartsFactory({ deployId, env, suffix, resources, replicas, image, namespace, volumes, cmd }) {
       if (!cmd)
         cmd = [
-          `npm install -g npm@11.2.0`,
-          `npm install -g underpost`,
+          // `npm install -g npm@11.2.0`,
+          // `npm install -g underpost`,
           `underpost secret underpost --create-from-env`,
           `underpost start --build --run ${deployId} ${env}`,
         ];
@@ -141,7 +142,8 @@ class UnderpostDeploy {
         ? JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.volume.json`, 'utf8'))
         : [];
       volumes = volumes.concat(confVolume);
-      const containerImage = image ? image : `localhost/rockylinux9-underpost:v${packageJson.version}`;
+      // const containerImage = image ? image : `localhost/rockylinux9-underpost:v${packageJson.version}`;
+      const containerImage = image ? image : `underpost/underpost-engine:v${packageJson.version}`;
       return `apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -164,6 +166,7 @@ spec:
       containers:
         - name: ${deployId}-${env}-${suffix}
           image: ${containerImage}
+          imagePullPolicy: ${containerImage.startsWith('localhost/') ? 'Never' : 'IfNotPresent'}
           envFrom:
             - secretRef:
                 name: underpost-config
@@ -624,6 +627,8 @@ EOF`);
                 path: instance.path,
                 fromPort: instance.fromPort,
                 toPort: instance.toPort,
+                fromDebugPort: instance.fromDebugPort,
+                toDebugPort: instance.toDebugPort,
                 traffic: Underpost.deploy.getCurrentTraffic(_deployId, { namespace, hostTest: instance.host }),
               });
             }
@@ -801,9 +806,10 @@ EOF`);
      * @memberof UnderpostDeploy
      */
     configMap(env, namespace = 'default') {
+      const cronDeployId = cronDeployIdResolve() || 'dd-cron';
       shellExec(`kubectl delete secret underpost-config -n ${namespace} --ignore-not-found`);
       shellExec(
-        `kubectl create secret generic underpost-config --from-env-file=/home/dd/engine/engine-private/conf/dd-cron/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
+        `kubectl create secret generic underpost-config --from-env-file=/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
       );
     },
     /**
@@ -1092,11 +1098,10 @@ ${renderHosts}`,
      * @param {string} targetTraffic - Target traffic status for the deployment.
      * @param {Array<string>} ignorePods - List of pod names to ignore.
      * @param {string} [namespace='default'] - Kubernetes namespace for the deployment.
-     * @param {string} [outLogType=''] - Type of log output.
      * @returns {object} - Object containing the ready status of the deployment.
      * @memberof UnderpostDeploy
      */
-    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default', outLogType = '') {
+    async monitorReadyRunner(deployId, env, targetTraffic, ignorePods = [], namespace = 'default') {
       let checkStatusIteration = 0;
       const checkStatusIterationMsDelay = 1000;
       const maxIterations = 3000;
@@ -1134,32 +1139,30 @@ ${renderHosts}`,
           }
         }
 
-        switch (outLogType) {
-          case 'underpost': {
-            let indexOf = -1;
-            for (const pod of result.notReadyPods) {
-              indexOf++;
-              const { NAME, out } = pod;
+        {
+          let indexOf = -1;
+          for (const pod of result.notReadyPods) {
+            indexOf++;
+            const { NAME, out } = pod;
 
-              if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match(deploymentId))
-                lastMsg[NAME] = 'Starting deployment';
-              else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('underpost'))
-                lastMsg[NAME] = 'Installing underpost cli';
-              else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('task'))
-                lastMsg[NAME] = 'Initializing setup task';
-              else if (out.match('Empty environment variables')) lastMsg[NAME] = 'Setup environment';
-              else if (out.match(`${deployId}-${env}-build-deployment`)) lastMsg[NAME] = 'Building apps/services';
-              else if (out.match(`${deployId}-${env}-initializing-deployment`))
-                lastMsg[NAME] = 'Initializing apps/services';
-              else if (!lastMsg[NAME]) lastMsg[NAME] = `Waiting for status`;
+            if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match(deploymentId))
+              lastMsg[NAME] = 'Starting deployment';
+            // else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('underpost'))
+            //   lastMsg[NAME] = 'Installing underpost cli';
+            else if (out.match('not') && out.match('found') && checkStatusIteration <= 20 && out.match('task'))
+              lastMsg[NAME] = 'Initializing setup task';
+            else if (out.match('Empty environment variables')) lastMsg[NAME] = 'Setup environment';
+            else if (out.match(`${deployId}-${env}-build-deployment`)) lastMsg[NAME] = 'Building apps/services';
+            else if (out.match(`${deployId}-${env}-initializing-deployment`))
+              lastMsg[NAME] = 'Initializing apps/services';
+            else if (!lastMsg[NAME]) lastMsg[NAME] = `Waiting for status`;
 
-              console.log(
-                'Target pod:',
-                NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
-                '| Status:',
-                lastMsg[NAME].bold.magenta,
-              );
-            }
+            console.log(
+              'Target pod:',
+              NAME[NAME.match('green') ? 'bgGreen' : 'bgBlue'].bold.black,
+              '| Status:',
+              lastMsg[NAME].bold.magenta,
+            );
           }
         }
         await timer(checkStatusIterationMsDelay);

package/src/cli/fs.js

@@ -75,6 +75,7 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @param {string} [options.storageFilePath=''] - The path to the storage configuration file.
      * @returns {Promise<void>} A promise that resolves when the recursive callback is complete.
      * @memberof UnderpostFileStorage
@@ -88,10 +89,50 @@ class UnderpostFileStorage {
         force: false,
         pull: false,
         git: false,
+        omitUnzip: false,
         storageFilePath: '',
       },
     ) {
       const { storage, storageConf } = Underpost.fs.getStorageConf(options);
+
+      // In recursive remove mode, delete every tracked storage key under the requested path,
+      // even when local files/directories are already missing.
+      if (options.rm === true) {
+        const normalizedPath = typeof path === 'string' ? path.trim() : '';
+        const basePath = normalizedPath.replace(/\/+$/, '');
+        const hasPathFilter = basePath.length > 0;
+
+        const associatedPaths = Object.keys(storage || {}).filter((storedPath) => {
+          if (!hasPathFilter) return true;
+          return storedPath === basePath || storedPath.startsWith(`${basePath}/`);
+        });
+
+        for (const associatedPath of associatedPaths) {
+          await Underpost.fs.delete(associatedPath);
+          if (storage) delete storage[associatedPath];
+        }
+
+        if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
+
+        Underpost.fs.writeStorageConf(storage, storageConf);
+
+        if (associatedPaths.length === 0)
+          logger.warn('No associated tracked storage paths found', { path: hasPathFilter ? basePath : '*' });
+        else
+          logger.info('Removed associated tracked storage paths', {
+            path: hasPathFilter ? basePath : '*',
+            removed: associatedPaths.length,
+          });
+
+        if (options.git === true) {
+          const gitPath = hasPathFilter ? basePath : '.';
+          shellExec(`cd ${gitPath} && git add .`);
+          shellExec(`underpost cmt ${gitPath} feat`);
+        }
+
+        return;
+      }
+
       const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(path);
       for (const relativePath of deleteFiles) {
         const _path = path + '/' + relativePath;
@@ -143,12 +184,13 @@ class UnderpostFileStorage {
      * @param {boolean} [options.force=false] - Flag to force file operations.
      * @param {boolean} [options.pull=false] - Flag to pull files from storage.
      * @param {boolean} [options.git=false] - Flag to use Git for file operations.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @returns {Promise<void>} A promise that resolves when the callback is complete.
      * @memberof UnderpostFileStorage
      */
     async callback(
       path,
-      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false },
+      options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
       if (options.recursive === true || options.git === true)
         return await Underpost.fs.recursiveCallback(path, options);
@@ -191,21 +233,36 @@ class UnderpostFileStorage {
      * @method pull
      * @description Pulls a file from Cloudinary.
      * @param {string} path - The path to the file to pull.
+     * @param {object} [options] - Pull options.
+     * @param {boolean} [options.omitUnzip=false] - If true, do not extract zip and keep downloaded zip file.
      * @returns {Promise<void>} A promise that resolves when the file is pulled.
      * @memberof UnderpostFileStorage
      */
-    async pull(path) {
+    async pull(path, options = { omitUnzip: false, force: false }) {
       Underpost.fs.cloudinaryConfig();
       const folder = dir.dirname(path);
       if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+      const zipPath = `${path}.zip`;
+
+      if (options.omitUnzip === true && options.force !== true && fs.existsSync(zipPath)) {
+        logger.warn('pull skipped, zip already exists and omit-unzip is enabled', { path, zipPath });
+        return;
+      }
+
       const downloadResult = await cloudinary.utils.download_archive_url({
         public_ids: [path],
         resource_type: 'raw',
       });
       logger.info('download result', downloadResult);
-      await Downloader.downloadFile(downloadResult, path + '.zip');
-      path = Underpost.fs.zip2File(path + '.zip');
-      fs.removeSync(path + '.zip');
+      await Downloader.downloadFile(downloadResult, zipPath);
+
+      if (options.omitUnzip === true) {
+        logger.warn('omit unzip enabled, keeping downloaded zip file', { path, zipPath });
+        return;
+      }
+
+      path = Underpost.fs.zip2File(zipPath);
+      fs.removeSync(`${path}.zip`);
     },
     async delete(path) {
       Underpost.fs.cloudinaryConfig();

package/src/cli/image.js

@@ -99,6 +99,7 @@ class UnderpostImage {
       if (!path) path = '.';
       if (!imageName) imageName = `rockylinux9-underpost:${Underpost.version}`;
       if (!imagePath) imagePath = '.';
+      if (imageName.match('/')) imageName = imageName.split('/')[1];
       if (!version) version = 'latest';
       version = imageName && imageName.match(':') ? '' : `:${version}`;
       const podManImg = `localhost/${imageName}${version}`;
@@ -178,6 +179,12 @@ class UnderpostImage {
      * @memberof UnderpostImage
      */
     pullDockerHubImage(options = { k3s: false, kubeadm: false, kind: false, dockerhubImage: '', version: '' }) {
+      if (options.dockerhubImage && options.dockerhubImage.startsWith('localhost')) {
+        logger.warn(`[image] pullDockerHubImage skipped — local image cannot be pulled from Docker Hub`, {
+          dockerhubImage: options.dockerhubImage,
+        });
+        return;
+      }
       if (options.dockerhubImage === 'underpost') {
         options.dockerhubImage = 'underpost/underpost-engine';
         if (!options.version) options.version = Underpost.version;
@@ -185,7 +192,42 @@ class UnderpostImage {
       if (!options.version) options.version = 'latest';
       const version = options.dockerhubImage && options.dockerhubImage.match(':') ? '' : `:${options.version}`;
       const image = `${options.dockerhubImage}${version}`;
-      if (options.kind === true) {
+      const targetKind = options.kind === true;
+      const targetK3s = options.k3s === true;
+      const targetKubeadm = options.kubeadm === true || (!targetKind && !targetK3s);
+
+      const requestedRepo = image.replace(/:[^/]+$/, '');
+      const requestedTag = image.match(/:([^/]+)$/)?.[1] || 'latest';
+      const normalizeRepo = (repo = '') =>
+        repo
+          .trim()
+          .replace(/^localhost\//, '')
+          .replace(/^docker\.io\//, '')
+          .replace(/^library\//, '');
+
+      const currentImages = UnderpostImage.API.list({
+        kind: targetKind,
+        kubeadm: targetKubeadm,
+        k3s: targetK3s,
+        log: false,
+      });
+
+      const existsInCluster = currentImages.some((row) => {
+        const rowImageRaw = String(row.IMAGE || row.image || '').trim();
+        if (!rowImageRaw) return false;
+        const rowImage = rowImageRaw.replace(/:[^/]+$/, '');
+        const rowTag = String(row.TAG || rowImageRaw.match(/:([^/]+)$/)?.[1] || '').trim();
+        return normalizeRepo(rowImage) === normalizeRepo(requestedRepo) && rowTag === requestedTag;
+      });
+
+      if (existsInCluster) {
+        logger.info(`[image] pull skipped. Image already loaded`, {
+          image,
+          clusterType: targetKind ? 'kind' : targetK3s ? 'k3s' : 'kubeadm',
+        });
+        return;
+      }
+      if (targetKind) {
         shellExec(`docker pull ${image}`);
         shellExec(`sudo kind load docker-image ${image}`);
       } else {

package/src/cli/index.js

@@ -46,6 +46,9 @@ program
   .option('--sync-env-port', 'Sync environment port assignments across all deploy IDs')
   .option('--single-replica', 'Build single replica folders instead of full client')
   .option('--build-zip', 'Create zip files of the builds')
+  .option('--split <mb>', 'Split generated zip files into parts of the specified size in MB')
+  .option('--unzip <build-prefix>', 'Extract a built client zip or split zip parts using the given build prefix')
+  .option('--merge-zip <build-prefix>', 'Merge split ZIP parts back into a single ZIP file for the given build prefix')
   .option('--lite-build', 'Skip full build (default is full build)')
   .option('--icons-build', 'Build icons')
   .description('Builds client assets, single replicas, and/or syncs environment ports.')
@@ -62,6 +65,7 @@ program
   .option('--build', 'Triggers the client-side application build process.')
   .option('--underpost-quickly-install', 'Uses Underpost Quickly Install for dependency installation.')
   .option('--skip-pull-base', 'Skips cloning repositories, uses current workspace code directly.')
+  .option('--skip-full-build', 'Skips the full client bundle build during deployment.')
   .action(Underpost.start.callback)
   .description('Initiates application servers, build pipelines, or other defined services based on the deployment ID.');
 
@@ -485,6 +489,7 @@ program
   .option('--recursive', 'Uploads files recursively from the specified path.')
   .option('--deploy-id <deploy-id>', 'Specifies the deployment configuration ID for file operations.')
   .option('--pull', 'Downloads the specified file.')
+  .option('--omit-unzip', 'With --pull, keeps the downloaded .zip file and skips extraction.')
   .option('--force', 'Forces the action, overriding any warnings or conflicts.')
   .option('--storage-file-path <storage-file-path>', 'Specifies a custom file storage path.')
   .description('Manages file storage, defaulting to file upload operations.')
@@ -613,7 +618,6 @@ program
   .option('--k3s', 'Sets the k3s cluster context for the runner execution.')
   .option('--kind', 'Sets the kind cluster context for the runner execution.')
   .option('--git-clean', 'Runs git clean on volume mount paths before copying.')
-  .option('--log-type <log-type>', 'Sets the log type for the runner execution.')
   .option('--deploy-id <deploy-id>', 'Sets deploy id context for the runner execution.')
   .option('--user <user>', 'Sets user context for the runner execution.')
   .option('--hosts <hosts>', 'Comma-separated list of hosts for the runner execution.')

package/src/cli/release.js

@@ -120,7 +120,7 @@ class UnderpostRelease {
         `./manifests/deployment/dd-default-development/deployment.yaml`,
         fs
           .readFileSync(`./manifests/deployment/dd-default-development/deployment.yaml`, 'utf8')
-          .replaceAll(`underpost:v${version}`, `underpost:v${newVersion}`),
+          .replaceAll(`underpost-engine:v${version}`, `underpost-engine:v${newVersion}`),
         'utf8',
       );
 
@@ -133,6 +133,62 @@ class UnderpostRelease {
           'utf8',
         );
 
+      // Update underpost/* image versions in all engine-*.cd.yml workflows.
+      for (const wf of fs.readdirSync(`./.github/workflows`)) {
+        if (!wf.match(/^engine-.+\.cd\.yml$/)) continue;
+        const wfPath = `./.github/workflows/${wf}`;
+        const updated = fs
+          .readFileSync(wfPath, 'utf8')
+          .replace(/underpost\/([^:'"]+):v[0-9]+\.[0-9]+\.[0-9]+/g, `underpost/$1:v${newVersion}`);
+        fs.writeFileSync(wfPath, updated, 'utf8');
+      }
+
+      // Update version tag in all runtime docker image workflows (type=raw,value=v<version>).
+      for (const wf of fs.readdirSync(`./.github/workflows`)) {
+        if (!wf.match(/^docker-image\..+\.ci\.yml$/) || wf === 'docker-image.ci.yml') continue;
+        const wfPath = `./.github/workflows/${wf}`;
+        fs.writeFileSync(
+          wfPath,
+          fs.readFileSync(wfPath, 'utf8').replaceAll(`type=raw,value=v${version}`, `type=raw,value=v${newVersion}`),
+          'utf8',
+        );
+      }
+
+      // Update image version in all conf.instances.json files for underpost/* images.
+      if (fs.existsSync(`./engine-private/conf`)) {
+        const confFiles = await fs.readdir(`./engine-private/conf`, { recursive: true });
+        for (const relativePath of confFiles) {
+          const filePath = `./engine-private/conf/${relativePath.replaceAll('\\', '/')}`;
+          if (filePath.split('/').pop() !== 'conf.instances.json' || !fs.existsSync(filePath)) continue;
+
+          let instances;
+          try {
+            instances = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+          } catch {
+            logger.warn(`Skipping invalid JSON file: ${filePath}`);
+            continue;
+          }
+
+          if (!Array.isArray(instances)) continue;
+
+          let updated = false;
+          for (const instance of instances) {
+            if (!instance || typeof instance !== 'object') continue;
+            if (!instance.image || typeof instance.image !== 'string') continue;
+            if (!instance.image.startsWith('underpost/')) continue;
+
+            const baseImage = instance.image.split('@')[0].split(':')[0];
+            const nextImage = `${baseImage}:v${newVersion}`;
+            if (instance.image !== nextImage) {
+              instance.image = nextImage;
+              updated = true;
+            }
+          }
+
+          if (updated) fs.writeFileSync(filePath, JSON.stringify(instances, null, 2), 'utf8');
+        }
+      }
+
       fs.writeFileSync(
         `./src/index.js`,
         fs.readFileSync(`./src/index.js`, 'utf8').replaceAll(`${version}`, `${newVersion}`),

package/src/cli/repository.js

@@ -21,7 +21,7 @@ import {
   buildReplicaId,
   writeEnv,
 } from '../server/conf.js';
-import { buildClient } from '../server/client-build.js';
+import { buildClient, unzipClientBuild, mergeClientBuildZip } from '../server/client-build.js';
 import { DefaultConf } from '../../conf.js';
 import Underpost from '../index.js';
 
@@ -642,6 +642,9 @@ class UnderpostRepository {
      * @param {boolean} [options.syncEnvPort=false] - If true, syncs environment port assignments across all deploy IDs.
      * @param {boolean} [options.singleReplica=false] - If true, builds single replica folders instead of full client.
      * @param {boolean} [options.buildZip=false] - If true, creates zip files of the builds.
+     * @param {string|number} [options.split=''] - Optional ZIP part size in MB. When set with buildZip, writes split parts.
+     * @param {string} [options.unzip=''] - Optional build ZIP prefix to extract from ./build.
+     * @param {string} [options.mergeZip=''] - Optional build prefix to merge split ZIP parts into a single ZIP.
      * @param {boolean} [options.liteBuild=false] - If true, skips full build (default is full build).
      * @param {boolean} [options.iconsBuild=false] - If true, builds icons.
      * @returns {Promise<boolean>} A promise that resolves when the build is complete.
@@ -656,12 +659,31 @@ class UnderpostRepository {
         syncEnvPort: false,
         singleReplica: false,
         buildZip: false,
+        split: '',
+        unzip: '',
+        mergeZip: '',
         liteBuild: false,
         iconsBuild: false,
       },
     ) {
       return new Promise(async (resolve, reject) => {
         try {
+          if (options.mergeZip) {
+            mergeClientBuildZip({
+              buildPrefix: options.mergeZip,
+              logger,
+            });
+            return resolve(true);
+          }
+
+          if (options.unzip) {
+            unzipClientBuild({
+              buildPrefix: options.unzip,
+              logger,
+            });
+            return resolve(true);
+          }
+
           // Handle singleReplica operation (must run before syncEnvPort to ensure replica dirs exist)
           if (options.singleReplica) {
             const replicaPath = path;
@@ -804,6 +826,9 @@ class UnderpostRepository {
             let argPath = path ? path.split(',') : [];
             let deployIdSingleReplicas = [];
             let singleReplicaHosts = [];
+            const isReplicaContext = resolvedDeployId
+              ? fs.existsSync(`./engine-private/replica/${resolvedDeployId}`)
+              : false;
             const serverConf = resolvedDeployId
               ? readConfJson(resolvedDeployId, 'server', { loadReplicas: true })
               : Config.default.server;
@@ -814,7 +839,7 @@ class UnderpostRepository {
                 if (argHost.length && argPath.length && (!argHost.includes(host) || !argPath.includes(path))) {
                   delete serverConf[host][path];
                 } else {
-                  if (serverConf[host][path].singleReplica && serverConf[host][path].replicas) {
+                  if (!isReplicaContext && serverConf[host][path].singleReplica && serverConf[host][path].replicas) {
                     singleReplicaHosts.push({ host, path });
                     deployIdSingleReplicas = deployIdSingleReplicas.concat(
                       serverConf[host][path].replicas.map((replica) =>
@@ -827,10 +852,17 @@ class UnderpostRepository {
             }
             await buildClient({
               buildZip: options.buildZip || false,
+              split: options.split || '',
               fullBuild: options.liteBuild ? false : true,
               iconsBuild: options.iconsBuild || false,
             });
-            for (const replicaDeployId of deployIdSingleReplicas) await Underpost.repo.client(replicaDeployId);
+            for (const replicaDeployId of deployIdSingleReplicas) {
+              if (!fs.existsSync(`./engine-private/replica/${replicaDeployId}`)) {
+                logger.warn('Skip replica client build: replica folder not found', { replicaDeployId });
+                continue;
+              }
+              await Underpost.repo.client(replicaDeployId);
+            }
 
             return resolve(true);
           }