@xuda.io/drive_module 1.1.1489 → 1.1.1491

package/index.mjs.premerge.bak

@@ -0,0 +1,3514 @@
+import path from 'path';
+import _ from 'lodash';
+import { rimraf } from 'rimraf';
+import fse from 'fs-extra';
+import unzipper from 'unzipper';
+import fs from 'fs';
+import tesseract from 'node-tesseract-ocr';
+import countryLanguage from 'country-language';
+import url from 'url';
+import { convertPDF } from 'pdf2image';
+import mammoth from 'mammoth';
+import xlsx from 'node-xlsx';
+import { imageSize } from 'image-size';
+import { getPackageManifest } from 'query-registry';
+
+// AWS SDK v3 Imports
+import { S3Client, GetObjectCommand, DeleteObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+
+console.log('Drive Module loaded...');
+
+global._conf = (
+  await import(path.join(process.env.XUDA_HOME, process.env.XUDA_CONFIG), {
+    with: { type: 'json' },
+  })
+).default;
+
+const _common = await import(path.join(process.env.XUDA_HOME, 'common', 'xuda_node_common.mjs'));
+const _utils = await import(path.join(process.env.XUDA_HOME, 'common', 'xuda-cpi-utils.mjs'));
+const { get_account_default_project_id } = await import(path.join(process.env.XUDA_HOME, 'common', 'cache_cpi.mjs'));
+
+const module_path = path.join(process.env.XUDA_HOME, 'cpi') + (!_conf.is_debug ? '/node_modules/@xuda.io' : '');
+const fs_module = await import(`${module_path}/fs_module/index.mjs`);
+const db_module = await import(`${module_path}/db_module/index.mjs`);
+
+// const account_msa = await import(`${module_path}/account_module/index_msa.mjs`);
+
+const misc_msa = await import(`${module_path}/misc_module/index_msa.mjs`);
+
+////////////////////////////////////////////
+
+const get_studio_path = (raw_path, ref, file_name) => {
+  return raw_path.replaceAll(path.join(_conf.studio_drive_path, ref), '').replaceAll('/' + file_name, '') || '/';
+};
+
+// Helper to get S3 Client
+// const getS3Client = (region) => {
+//   const endpoint = _conf.storage_bucket[region || process.env.XUDA_HOSTNAME].endpoint;
+//   // AWS SDK v3 requires protocol in endpoint, v2 didn't always strict check
+//   const formattedEndpoint = endpoint.startsWith('http') ? endpoint : `https://${endpoint}`;
+
+//   return new S3Client({
+//     endpoint: formattedEndpoint,
+//     region: _conf.storage_bucket[region || process.env.XUDA_HOSTNAME].region,
+//     credentials: {
+//       accessKeyId: _conf.digitalocean.spaces_access_key,
+//       secretAccessKey: _conf.digitalocean.spaces_secret_key,
+//     },
+//     forcePathStyle: false, // DigitalOcean Spaces supports virtual-hosted style
+//   });
+// };
+
+export const get_drive_files = async (req) => {
+  try {
+    const { from = 0, to = 99999, drive_type, app_id, uid, type, date, search_string, sort_by = 'name', sort_dir = 'desc', path: file_path } = req;
+
+    let { tags = [] } = req;
+
+    if (!['asc', 'desc'].includes(sort_dir)) {
+      throw 'invalid value for sort_dir (asc/desc)';
+    }
+
+    let tags_query = {};
+    const sort_by_obj = {
+      name: [type === 'file' ? 'originalname' : 'folder_name'],
+      date: ['date_modified'],
+    };
+
+    if (!sort_by_obj[sort_by]) {
+      throw 'invalid value for sort_by value';
+    }
+
+    let sort = [];
+    for (let item of sort_by_obj[sort_by]) {
+      sort.push({ [item]: sort_dir });
+    }
+
+    let opt = {
+      selector: {
+        docType: `${drive_type}_drive`,
+        stat: 3,
+        type,
+      },
+      limit: to - from,
+      skip: from,
+      sort,
+    };
+
+    if (!_conf.superuser_account_ids.includes(uid)) {
+      opt.selector.is_system = { $exists: false };
+    }
+
+    // The Starred view is flat — bookmarked items across ALL folders — so it
+    // ignores the folder path; the normal listing scopes to the current folder.
+    if (req.starred) {
+      opt.selector.starred = true;
+    } else if (file_path) {
+      opt.selector.file_path = file_path;
+    }
+
+    if (search_string) {
+      let mix_conditions;
+      tags_query = search_string
+        .split(' ')
+        .filter((e) => e.includes(':'))
+        .reduce(
+          (ret, val) => {
+            let tagKey = val.split(':')[0];
+            let tagVal = val.split(':')[1];
+
+            if (tagKey === 'tag') {
+              tags.push(tagVal);
+              return;
+            }
+            mix_conditions = true;
+            if (tagKey === 'name') {
+              ret.$or.push({ originalname: { $regex: `(?i)${tagVal}` } });
+            }
+            if (tagKey === 'mime') {
+              ret.$or.push({ mime: { $regex: `(?i)${tagVal}` } });
+            }
+            if (tagKey === 'ext') {
+              ret.$or.push({ file_ext: { $regex: `(?i)${tagVal}` } });
+            }
+
+            return ret;
+          },
+          {
+            $or: [],
+          },
+        );
+
+      let new_search = search_string
+        .split(' ')
+        .filter((e) => !e.includes(':'))
+        .filter((e) => e)
+        .join(' ');
+
+      if (new_search) {
+        opt.selector = {
+          ...opt.selector,
+          ...{
+            $or: [
+              {
+                ocr: {
+                  $regex: `(?i)${new_search}`,
+                },
+              },
+              {
+                originalname: {
+                  $regex: `(?i)${new_search}`,
+                },
+              },
+            ],
+          },
+        };
+      }
+
+      if (mix_conditions) {
+        if (new_search) {
+          tags_query.$or = [
+            ...tags_query.$or,
+            {
+              ocr: {
+                $regex: `(?i)${new_search}`,
+              },
+            },
+            {
+              originalname: {
+                $regex: `(?i)${new_search}`,
+              },
+            },
+          ];
+        }
+        opt.selector = { ...opt.selector, ...tags_query };
+      }
+    }
+
+    if (tags?.length) {
+      opt.selector.tags = {
+        $all: tags,
+      };
+    }
+
+    validate_drive_type(drive_type);
+
+    function formatBytes(bytes) {
+      if (bytes < 1024) return bytes + ' Bytes';
+      else if (bytes < 1048576) return (bytes / 1024).toFixed(2) + ' KB';
+      else if (bytes < 1073741824) return (bytes / 1048576).toFixed(2) + ' MB';
+      else return (bytes / 1073741824).toFixed(2) + ' GB';
+    }
+
+    const fetch_drive_files = async (ret, file_doc, app_id_reference, uid, datasource_id, domain = process.env.XUDA_HOSTNAME, app_obj) => {
+      let files = {
+        path: file_path || '/',
+        name: file_doc?.data?.folder_name || '/',
+        file_path: file_path || '/',
+        sizeInBytes: 0,
+        children: [],
+        path: file_path,
+      };
+
+      for await (let doc of ret.docs) {
+        if (doc.type === 'file') {
+          let ts = '';
+          if (doc.date_modified && Date.now() - doc.date_modified < 4320 * 1000) {
+            ts = '?ts=' + Date.now();
+          } else if (app_obj?.app_build_id) {
+            ts = '?ts=' + app_obj?.app_build_id;
+          }
+          debugger;
+          try {
+            files.sizeInBytes += doc.size;
+            files.children.push({
+              name: doc.originalname,
+              sizeInBytes: doc.size,
+              size: formatBytes(doc.size),
+              extension: doc?.file_ext?.substr(1),
+              type: doc.type,
+              access_link: `https://${domain}/${drive_type}-drive/${datasource_id || app_id_reference || uid}/${doc._id}${ts}`,
+              is_archive: doc.is_archive,
+              public: doc.public,
+              path: doc.file_path,
+              date_created: doc.date_created,
+              date_modified: doc.date_modified,
+              file_path: path.join(doc.file_path, doc.originalname),
+              tags: doc.tags || [],
+              starred: !!doc.starred,
+            });
+          } catch (err) {
+            console.error(err.message);
+          }
+        }
+        if (doc.type === 'directory') {
+          try {
+            const sizeInBytes = await get_folder_size(file_path, drive_type, app_id_reference, uid);
+            files.sizeInBytes += sizeInBytes;
+            files.children.push({
+              sizeInBytes,
+              size: formatBytes(sizeInBytes),
+              name: doc.folder_name,
+              path: doc.file_path, //'/' + doc._id,
+              file_path: path.join(doc.file_path, doc.folder_name), //'/' + doc._id,
+              type: doc.type,
+              is_folder: true,
+              date_created: doc.date_created,
+              tags: doc.tags || [],
+              starred: !!doc.starred,
+            });
+          } catch (err) {
+            console.error(err.message);
+          }
+        }
+      }
+      files.size = formatBytes(files.sizeInBytes);
+
+      return files;
+    };
+
+    const get_workspace_files = async () => {
+      const app_id_reference = await _common.get_project_app_id(app_id);
+      opt.selector.docType = 'workspace_drive';
+
+      const ret = await db_module.find_app_couch_query(app_id, opt);
+
+      const file_doc = await db_module.get_app_couch_doc(app_id, path.basename(file_path) || '/');
+
+      const { data: app_obj } = await db_module.get_app_obj(app_id);
+
+      const ret_fetch_drive_files = await fetch_drive_files(ret, file_doc, app_id_reference, null, app_obj.app_datacenter_id, app_obj.is_deployment ? app_obj.app_access_url : undefined, app_obj);
+      return {
+        code: 1,
+        data: ret_fetch_drive_files,
+      };
+    };
+    const get_user_files = async () => {
+      opt.selector.docType = 'user_drive';
+      // opt.selector.uid = uid;
+      // const ret = await find_contact_query(uid, opt);
+      // const file_doc = await get_user_drive_file(uid, path.basename(file_path) || '/');
+
+      const app_id = await get_account_default_project_id(uid);
+      const ret = await db_module.find_app_couch_query(app_id, opt);
+
+      const file_doc = await db_module.get_app_couch_doc(app_id, path.basename(file_path) || '/');
+
+      return {
+        code: 1,
+        data: await fetch_drive_files(ret, file_doc, app_id, uid),
+      };
+    };
+    const get_studio_files = async () => {
+      if (search_string) {
+        const app_id_reference = await _common.get_project_app_id(app_id);
+        opt.selector.docType = 'studio_drive';
+        const ret = await db_module.find_app_couch_query(app_id, opt);
+
+        const file_doc = await db_module.get_app_couch_doc(app_id, path.basename(file_path) || '/');
+
+        return {
+          code: 1,
+          data: await fetch_drive_files(ret, file_doc, app_id_reference, null),
+        };
+      }
+
+      const app_id_master = await _common.get_project_app_id(app_id, true);
+
+      let directoryPath = path.join(_conf.studio_drive_path, app_id_master, file_path || '/');
+
+      const options = {
+        stat: true,
+        symbolicLinks: false,
+        size: true,
+        hash: false,
+        depth: 1,
+      };
+
+      if (!(await file_exists(directoryPath))) {
+        await create_directory(directoryPath, 0o775, true);
+      }
+
+      const dree_ret = await fs_module.dree_scan(directoryPath, options);
+
+      let tree = dree_ret.data;
+
+      const rep = async (file_path, type) => {
+        file_path = file_path.replace(`${_conf.studio_drive_path}/${app_id_master}/`, '');
+
+        return `https://${process.env.XUDA_HOSTNAME}/studio-drive/${app_id_master}/${file_path}`;
+      };
+
+      const drill = async (node) => {
+        let i = 0;
+        let values_to_delete = [];
+
+        for await (let val of node) {
+          i++;
+          // filter by file type
+          if (type && type.toLowerCase() !== val.type.toLowerCase()) {
+            values_to_delete.push(i - 1);
+            continue;
+          }
+
+          const internal_path = val.path;
+          const directory_path = get_studio_path(val.path, app_id_master, val.relativePath);
+          const file_path = path.join(directory_path, val.name);
+
+          let ret = await db_module.get_app_couch_doc(app_id_master, file_path);
+
+          if (ret.code > -1) {
+            if (val.type === 'file') {
+              val.cy_data = ret.data;
+              val.access_link = await rep(internal_path, drive_type);
+            }
+            if (val.type === 'directory') {
+              val.name = ret.data.folder_name;
+              val.sizeInBytes = await get_folder_size(internal_path, drive_type, app_id_master);
+            }
+
+            delete ret.data._id;
+            delete ret.data._rev;
+            delete ret.data.docType;
+            delete ret.data.stat;
+          } else {
+            if (val.type === 'directory') {
+              val.sizeInBytes = await get_folder_size(internal_path, drive_type, app_id_master);
+            }
+            val.access_link = await rep(val.path, 'studio');
+          }
+          val.date_created = new Date(val.stat.birthtime).valueOf();
+          delete val.stat;
+
+          val.path = directory_path;
+          val.file_path = file_path;
+          val.tags = ret?.data?.tags || [];
+        }
+        for await (let index of values_to_delete.reverse()) {
+          node.splice(index, 1);
+        }
+      };
+
+      if (tree?.children) {
+        if (type === 'file') {
+          tree.children = tree.children.filter((e) => e.type === type).slice(from, to + 1);
+        }
+        await drill(tree.children);
+      } else {
+        tree = {
+          children: [],
+          name: tree?.name,
+          size: 0,
+        };
+      }
+
+      tree.path = get_studio_path(tree.path || tree.name, app_id_master, tree?.name || '');
+      tree.file_path = path.join(tree.path, tree.name);
+
+      return {
+        code: 200,
+        data: tree,
+      };
+    };
+
+    switch (drive_type) {
+      case 'studio':
+        return get_studio_files();
+
+      case 'workspace':
+        return get_workspace_files();
+
+      case 'user':
+        return get_user_files();
+
+      default:
+        throw new Error('drive_type error');
+    }
+  } catch (err) {
+    return {
+      code: -1,
+      data: err.message,
+    };
+  }
+};
+
+export const get_drive_file_info = async (req, job_id, headers) => {
+  try {
+    const { type, drive_type, uid, app_id, file_path } = req;
+
+    let doc = await get_drive_doc(type, drive_type, app_id, uid, file_path, headers);
+
+    delete doc._id;
+    delete doc._rev;
+
+    delete doc.docType;
+    delete doc.stat;
+    if (doc.bucket) {
+      doc.regions = Object.entries(doc.bucket).length;
+    }
+
+    delete doc.bucket;
+
+    if (doc.uid) {
+      let ret = await db_module.get_couch_doc('xuda_accounts', doc.uid);
+      doc.account_info = ret.data.account_info;
+    }
+    if (req.drive_type === 'workspace') {
+      const app_id_master = await _common.get_project_app_id(app_id, true);
+      const ret = await db_module.get_app_obj(app_id_master);
+
+      if (ret.code < 0) {
+        return ret;
+      }
+      const app_obj = ret.data;
+      doc.app_name = app_obj.app_name;
+    }
+
+    return {
+      code: 200,
+      data: {
+        name: doc.originalname,
+        cy_data: doc,
+        exif_data: doc.exif_data,
+      },
+    };
+  } catch (err) {
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+};
+
+const get_folder_files = async function (uid, app_id, drive_type, path) {
+  const files_ret = await get_drive_files({ uid, app_id, drive_type, type: 'file', path });
+  const directory_ret = await get_drive_files({ uid, app_id, drive_type, type: 'directory', path });
+
+  return [...(files_ret.data.children || []), ...(directory_ret.data.children || [])];
+};
+
+// Recursively flatten an entire folder subtree into a list of
+// { type, file_path } entries (every file + subfolder at any depth).
+// Each child returned by get_folder_files already carries its FULL
+// file_path (path.join(parent, name)), so we recurse on that directly.
+// Used by delete_drive_files to remove a non-empty folder and all of
+// its contents instead of refusing with "Directory is not empty".
+const collect_folder_descendants = async function (uid, app_id, drive_type, folder_full_path) {
+  const out = [];
+  const children = await get_folder_files(uid, app_id, drive_type, folder_full_path);
+  for (const child of children) {
+    out.push({ type: child.type, file_path: child.file_path });
+    if (child.type === 'directory') {
+      const sub = await collect_folder_descendants(uid, app_id, drive_type, child.file_path);
+      out.push(...sub);
+    }
+  }
+  return out;
+};
+
+export const delete_drive_files = async (req, job_id, headers) => {
+  let ret = [];
+  try {
+    const { drive_type, app_id, files_arr, uid } = req;
+    validate_drive_type(drive_type);
+
+    if (!Array.isArray(files_arr)) {
+      return {
+        code: -400,
+        data: 'error - files_arr must be Array',
+      };
+    }
+
+    // get docs
+    let docs = [];
+    for await (const file of files_arr) {
+      let doc;
+      try {
+        doc = await get_drive_doc(file.type, drive_type, app_id, uid, file.file_path, headers);
+        doc.ts = Date.now();
+        doc.stat = 4;
+        docs.push(doc);
+      } catch (error) {}
+
+      if (doc?.type === 'directory') {
+        // Recursively delete the folder's entire subtree. Previously this
+        // refused with "Directory is not empty" — folders could never be
+        // deleted once they had any content. Now we gather every
+        // descendant (files + nested folders), fetch each real doc, mark
+        // it deleted (stat=4), and let the same bulk-save + cleanup below
+        // handle docs + filesystem/bucket removal for the whole tree.
+        const folder_full_path = path.join(doc.file_path, doc.folder_name);
+        const descendants = await collect_folder_descendants(uid, app_id, drive_type, folder_full_path);
+        for (const entry of descendants) {
+          try {
+            const child_doc = await get_drive_doc(entry.type, drive_type, app_id, uid, entry.file_path, headers);
+            child_doc.ts = Date.now();
+            child_doc.stat = 4;
+            docs.push(child_doc);
+          } catch (error) {}
+        }
+      }
+    }
+    // delete bulk docs
+    let app_id_delete;
+    switch (drive_type) {
+      case 'workspace':
+      case 'studio': {
+        app_id_delete = await _common.get_project_app_id(app_id);
+        break;
+      }
+
+      case 'user': {
+        app_id_delete = await get_account_default_project_id(uid);
+        break;
+      }
+      default:
+        break;
+    }
+    ret = await db_module.sava_app_couch_bulk_docs(app_id_delete, docs);
+
+    // cleanup
+    setTimeout(async () => {
+      for (const doc of docs) {
+        try {
+          switch (drive_type) {
+            case 'studio': {
+              const app_id_reference = await _common.get_project_app_id(app_id);
+              // Resolve the on-disk path INCLUDING the doc's parent
+              // file_path (the old code dropped it, so nested files were
+              // never removed). For directory docs we rimraf the folder
+              // itself — recursively clearing the whole subtree on disk in
+              // one shot (the per-descendant-file rimrafs then no-op).
+              const rel = doc.type === 'directory' ? path.join(doc.file_path || '/', doc.folder_name) : path.join(doc.file_path || '/', doc.originalname);
+              const target_path = path.join(_conf[`studio_drive_path`], app_id_reference, rel);
+
+              rimraf.sync(target_path);
+
+              misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id_reference);
+              break;
+            }
+
+            case 'workspace': {
+              if (doc.type === 'file') {
+                try {
+                  if (doc.bucket) {
+                    await delete_file_from_bucket(doc.bucket);
+                  } else {
+                    const { data: app_obj } = await db_module.get_app_obj(app_id);
+                    if (app_obj?.app_type === 'datacenter') {
+                      const host = `root@${app_obj.app_hosting_server.ip}`;
+                      await _utils.run_ssh_script(`ssh ${host} "mv /var/xuda/workspace_drive/${doc.server_file_name} /tmp/;" `);
+                    } else if (app_obj?.is_deployment) {
+                      const { data: datacenter_obj } = await db_module.get_app_obj(app_obj.app_datacenter_id);
+                      const host = `root@${datacenter_obj.app_hosting_server.ip}`;
+                      await _utils.run_ssh_script(`ssh ${host} "mv /var/xuda/workspace_drive/${doc.server_file_name} /tmp/;" `);
+                    }
+                  }
+                } catch (error) {}
+              }
+
+              break;
+            }
+
+            case 'user': {
+              if (doc.type === 'file') {
+                try {
+                  await delete_file_from_bucket(doc.bucket);
+                } catch (error) {}
+              }
+
+              break;
+            }
+            default:
+              break;
+          }
+        } catch (error) {}
+      }
+    }, 1000);
+    return {
+      code: 200,
+      data: ret,
+    };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+export const update_drive_file = async (req, job_id, headers, file_obj) => {
+  try {
+    const { drive_type, app_id, file_path, uid } = req;
+    validate_drive_type(drive_type);
+
+    const originalname = file_obj?.['originalname'];
+
+    const file_name = path.basename(file_path);
+
+    if (!originalname) {
+      return { code: -4, data: 'file data missing' };
+    }
+
+    let doc = await get_drive_doc('file', drive_type, app_id, uid, file_path, headers);
+
+    let target_file = file_path;
+    const master_id = await _common.get_project_app_id(app_id, true);
+    const tempPath = file_obj.path;
+    if (drive_type === 'studio') {
+      const target_dir = path.join(_conf[`studio_drive_path`], master_id, file_path);
+      try {
+        fse.unlinkSync(target_dir);
+      } catch (error) {}
+
+      fse.copyFileSync(tempPath, target_dir);
+    }
+
+    doc.date_modified = Date.now();
+
+    const fsPromises = fs.promises;
+    const stat = await fsPromises.stat(tempPath);
+    if (stat.isFile()) {
+      doc.size = stat.size;
+    }
+
+    doc = { ...doc, ...(await get_file_info(tempPath)) };
+
+    let save_ret;
+    let ref;
+    switch (drive_type) {
+      case 'studio': {
+        ref = await _common.get_project_app_id(app_id, true);
+        const app_id_reference = await _common.get_project_app_id(app_id);
+        save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+
+        misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id_reference);
+        break;
+      }
+      case 'workspace': {
+        const app_id_reference = await _common.get_project_app_id(app_id);
+        const app_id_master = await _common.get_project_app_id(app_id, true);
+        ref = app_id_master;
+
+        const { data: app_obj } = await db_module.get_app_obj(app_id);
+        if (app_obj?.app_type === 'datacenter') {
+          const host = `root@${app_obj.app_hosting_server.ip}`;
+          await _utils.run_ssh_script(`scp ${tempPath} ${host}:/var/xuda/workspace_drive/${doc.server_file_name}; `);
+        } else if (app_obj?.is_deployment) {
+          const { data: datacenter_obj } = await db_module.get_app_obj(app_obj.app_datacenter_id);
+          const host = `root@${datacenter_obj.app_hosting_server.ip}`;
+          await _utils.run_ssh_script(`scp ${tempPath} ${host}:/var/xuda/workspace_drive/${doc.server_file_name}; `);
+        } else {
+          doc.bucket[`${process.env.XUDA_HOSTNAME}`] = await upload_file_to_spaces(tempPath, app_id_master, drive_type, doc.server_file_name);
+        }
+
+        save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+        break;
+      }
+      case 'user': {
+        ref = await get_account_default_project_id(uid);
+        doc.bucket[`${process.env.XUDA_HOSTNAME}`] = await upload_file_to_spaces(tempPath, ref, drive_type, file_name);
+        save_ret = await save_user_drive_file(uid, doc);
+        break;
+      }
+      default:
+        break;
+    }
+
+    fse.unlinkSync(tempPath);
+
+    if (save_ret.code < 0) {
+      return save_ret;
+    }
+    const server_file_name = `https://${process.env.XUDA_HOSTNAME}/${drive_type}-drive${drive_type === 'studio' ? `/${master_id}/${target_file}` : file_name}`;
+
+    let file_url = get_file_url(drive_type, file_name, ref);
+
+    return {
+      code: 760,
+      data: {
+        server_file_name,
+        filename: file_obj.originalname,
+        file_url,
+        file_path,
+      },
+    };
+  } catch (err) {
+    return { code: -400, data: err };
+  }
+};
+
+export const create_drive_folder = async (req, job_id, headers) => {
+  try {
+    const { drive_type, app_id, folder_name, tags, uid, is_system, path: file_path } = req;
+    validate_drive_type(drive_type);
+
+    let folder_id;
+
+    let target_dir;
+    let folder_exist;
+    let save_ret;
+
+    let tags_arr = [];
+    if (!_.isEmpty(tags)) {
+      if (typeof tags === 'string') {
+        tags_arr = tags.split(',');
+      } else if (_.isArray(tags)) {
+        tags_arr = tags;
+      }
+    }
+
+    let doc = {
+      docType: `${drive_type}_drive`,
+      stat: 3,
+      folder_name,
+      uid,
+      date_created: Date.now(),
+      date_modified: 0,
+      ip: headers?.['cf-connecting-ip'],
+      country: headers?.['cf-ipcountry'],
+      is_folder: true,
+      type: 'directory',
+      file_path,
+      is_system,
+      tags: tags_arr,
+    };
+
+    let check_req = {
+      app_id,
+      uid,
+      drive_type,
+      file_path: doc.file_path,
+      folder_name,
+      type: doc.type,
+    };
+
+    const check_existing_file_ret = await check_drive_file(check_req);
+
+    if (check_existing_file_ret.code < 0) {
+      throw new Error(check_existing_file_ret.data);
+    }
+
+    switch (drive_type) {
+      case 'studio': {
+        folder_id = req.folder_name;
+        const app_id_master = await _common.get_project_app_id(app_id, true);
+        // if (!file_path.includes(app_id_master)) {
+        //   return {
+        //     code: -1,
+        //     data: 'error - file path unauthorized',
+        //   };
+        // }
+
+        target_dir = path.join(file_path, folder_id);
+        const fs_target_dir = path.join(_conf[`studio_drive_path`], app_id_master, target_dir);
+        folder_exist = await file_exists(fs_target_dir);
+        if (folder_exist) {
+          throw new Error('folder exist');
+        }
+        await create_directory(fs_target_dir, 0o775, true);
+        doc._id = target_dir;
+        save_ret = await db_module.save_app_couch_doc(app_id_master, doc);
+        misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id_master);
+        break;
+      }
+
+      case 'workspace': {
+        folder_id = 'drive_folder_' + _utils.UUID();
+        let app_id_reference = await _common.get_project_app_id(app_id);
+        doc._id = folder_id;
+        save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+        break;
+      }
+
+      case 'user': {
+        folder_id = 'drive_folder_' + _utils.UUID();
+        doc._id = folder_id;
+        save_ret = await save_user_drive_file(uid, doc);
+        break;
+      }
+      default:
+        break;
+    }
+
+    if (save_ret.code < 0) {
+      return save_ret;
+    }
+
+    return {
+      code: 200,
+      data: target_dir,
+    };
+  } catch (err) {
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+};
+
+export const rename_drive_file = async (req, job_id, headers) => {
+  try {
+    const { drive_type, app_id, file_name_to, file_path, uid } = req;
+    validate_drive_type(drive_type);
+
+    let doc = await get_drive_doc('file', drive_type, app_id, uid, file_path, headers);
+
+    if (drive_type === 'studio') {
+      await fs_module.rename(file_path, file_name_to);
+      let app_id_master = await _common.get_project_app_id(app_id, true);
+
+      doc._delete = true;
+      await db_module.save_app_couch_doc(app_id_master, doc);
+
+      doc._id = file_name_to;
+      delete doc._rev;
+    }
+
+    doc.date_modified = Date.now();
+    doc.originalname = file_name_to;
+    let save_ret;
+
+    switch (drive_type) {
+      case 'workspace':
+      case 'studio':
+        const app_id_reference = await _common.get_project_app_id(app_id);
+        save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+        break;
+
+      case 'user':
+        save_ret = await save_user_drive_file(uid, doc);
+        break;
+
+      default:
+        break;
+    }
+
+    if (save_ret.code < 0) {
+      throw new Error(save_ret.data);
+    }
+
+    return {
+      code: 200,
+      data: file_name_to,
+    };
+  } catch (err) {
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+};
+
+export const rename_drive_folder = async (req) => {
+  try {
+    debugger;
+    const { drive_type, app_id, curr_path, new_path, uid } = req;
+    validate_drive_type(drive_type);
+
+    const files_in_directory = await get_folder_files(uid, app_id, drive_type, curr_path);
+    if (files_in_directory?.length) {
+      throw new Error(`Directory is not empty`);
+    }
+
+    let doc_ret;
+    switch (drive_type) {
+      case 'studio': {
+        const app_id_reference = await _common.get_project_app_id(app_id);
+
+        if (!new_path.includes(app_id_reference)) {
+          throw new Error('error - new_path unauthorized');
+        }
+
+        doc_ret = await db_module.get_app_couch_doc(app_id_reference, curr_path);
+        await fs_module.rename(curr_path, new_path);
+        doc_ret.data._delete = true;
+        await db_module.save_app_couch_doc(app_id_reference, doc_ret.data);
+
+        doc_ret.data._id = new_path;
+        delete doc_ret.data._rev;
+
+        misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id_reference);
+        break;
+      }
+      case 'workspace': {
+        const app_id_reference = await _common.get_project_app_id(app_id);
+        doc_ret = await db_module.get_app_couch_doc(app_id_reference, curr_path);
+        if (doc_ret.code < 0) {
+          throw new Error(doc_ret.data);
+        }
+
+        break;
+      }
+
+      case 'user':
+        doc_ret = await get_user_drive_file(uid, curr_path);
+        if (doc_ret.code < 0) {
+          throw new Error(doc_ret.data);
+        }
+
+        break;
+
+      default:
+        break;
+    }
+
+    if (doc_ret.code > -1) {
+      let doc = doc_ret.data;
+      doc.date_modified = Date.now();
+      doc.folder_name = new_path;
+      let save_ret;
+
+      switch (drive_type) {
+        case 'workspace':
+        case 'studio':
+          const app_id_reference = await _common.get_project_app_id(app_id);
+          save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+          break;
+
+        case 'user':
+          save_ret = await save_user_drive_file(uid, doc);
+          break;
+
+        default:
+          break;
+      }
+
+      if (save_ret.code < 0) {
+        throw new Error(save_ret.data);
+      }
+    }
+    return {
+      code: 200,
+      data: new_path,
+    };
+  } catch (err) {
+    // return err.message;
+
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+};
+
+export const update_drive_file_sharing_mode = async (req, job_id, headers) => {
+  try {
+    const { type, drive_type, uid, app_id, file_path, is_public } = req;
+
+    validate_drive_type(drive_type);
+
+    let doc = await get_drive_doc(type, drive_type, app_id, uid, file_path, headers);
+
+    doc.ts = Date.now();
+    doc.public = is_public;
+
+    return await save_drive_doc(drive_type, uid, app_id, doc);
+  } catch (err) {
+    return err.message;
+  }
+};
+
+// Toggle a file/folder's `starred` flag — a per-owner bookmark within the
+// account's own drive DB (mirrors update_drive_file_sharing_mode). The Starred
+// view is get_drive_files with `starred: true`.
+export const star_drive_file = async (req, job_id, headers) => {
+  try {
+    const { type, drive_type, uid, app_id, file_path, starred } = req;
+
+    validate_drive_type(drive_type);
+
+    let doc = await get_drive_doc(type, drive_type, app_id, uid, file_path, headers);
+
+    doc.ts = Date.now();
+    doc.starred = !!starred;
+
+    return await save_drive_doc(drive_type, uid, app_id, doc);
+  } catch (err) {
+    return err.message;
+  }
+};
+
+// Drive items shared *with* the current user. Drive shares are auto-accepted
+// team_request docs (access_type 'user_drive', stat 3) whose share_item_id is a
+// full path in the *sharer's* drive — so we resolve each owner's default project
+// and fetch the doc cross-account, returning the same {children:[]} shape as
+// get_drive_files so the frontend renders shared items identically.
+export const get_shared_with_me_files = async (req, job_id, headers) => {
+  try {
+    const { uid, type } = req;
+
+    const fmtBytes = (b = 0) =>
+      b < 1024 ? b + ' Bytes' : b < 1048576 ? (b / 1024).toFixed(2) + ' KB' : b < 1073741824 ? (b / 1048576).toFixed(2) + ' MB' : (b / 1073741824).toFixed(2) + ' GB';
+
+    const ownerCard = (o = {}) => ({
+      uid: o.uid,
+      email: o.email,
+      first_name: o.first_name,
+      last_name: o.last_name,
+      full_name: o.full_name,
+      profile_picture: o.profile_picture,
+      profile_avatar: o.profile_avatar,
+    });
+
+    const shares_ret = await db_module.find_couch_query('xuda_team', {
+      selector: { docType: 'team_request', access_type: 'user_drive', team_req_to_uid: uid, team_req_stat: 3 },
+    });
+    const shares = shares_ret?.docs || [];
+
+    const children = [];
+    for (const share of shares) {
+      const from_uid = share.team_req_from_uid;
+      const item_path = share.share_item_id;
+      if (!from_uid || !item_path) continue;
+
+      // share_item_type may be absent on older shares → probe file then directory.
+      const try_types = share.share_item_type ? [share.share_item_type] : ['file', 'directory'];
+      let doc = null;
+      for (const t of try_types) {
+        try {
+          doc = await get_drive_doc(t, 'user', null, from_uid, item_path, headers);
+          if (doc) break;
+        } catch (e) {}
+      }
+      if (!doc) continue; // sharer deleted the item
+      if (type && doc.type !== type) continue;
+
+      const owner_pid = await get_account_default_project_id(from_uid);
+      const owner = ownerCard(share.sender_account_info);
+
+      if (doc.type === 'file') {
+        children.push({
+          name: doc.originalname,
+          sizeInBytes: doc.size,
+          size: fmtBytes(doc.size),
+          extension: doc?.file_ext?.substr(1),
+          type: doc.type,
+          access_link: `https://${process.env.XUDA_HOSTNAME}/user-drive/${owner_pid}/${doc._id}`,
+          is_archive: doc.is_archive,
+          public: doc.public,
+          path: doc.file_path,
+          date_created: doc.date_created,
+          date_modified: doc.date_modified,
+          file_path: path.join(doc.file_path, doc.originalname),
+          tags: doc.tags || [],
+          shared_by: owner,
+          owner_uid: from_uid,
+          share_id: share._id,
+        });
+      } else {
+        children.push({
+          name: doc.folder_name,
+          sizeInBytes: 0,
+          size: fmtBytes(0),
+          type: doc.type,
+          is_folder: true,
+          path: doc.file_path,
+          file_path: path.join(doc.file_path, doc.folder_name),
+          date_created: doc.date_created,
+          tags: doc.tags || [],
+          shared_by: owner,
+          owner_uid: from_uid,
+          share_id: share._id,
+        });
+      }
+    }
+
+    return { code: 1, data: { path: '/', name: 'Shared with me', file_path: '/', children, sizeInBytes: 0, size: fmtBytes(0) } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+export const get_shared_with_me_files_user = async (req, job_id, headers) => {
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // resolve from the authenticated session
+  return await get_shared_with_me_files(req, job_id, headers);
+};
+
+export const extract_drive_file = async (req, job_id, headers) => {
+  const { app_id, file_path, uid, drive_type } = req;
+
+  const app_id_master = await _common.get_project_app_id(app_id, true);
+  const app_id_reference = await _common.get_project_app_id(app_id);
+
+  let doc = await get_drive_doc('file', drive_type, app_id, uid, file_path, headers);
+
+  const ext = path.extname(file_path).toLowerCase();
+
+  const validation_ret = file_upload_validator(file_path);
+
+  if (!validation_ret.valid || validation_ret.category !== 'archive') {
+    throw new Error('error - invalid archive file');
+  }
+
+  if (!file_exists(req.file_path)) {
+    throw new Error('error - file not found');
+  }
+
+  try {
+    const extract_dir = path.dirname(file_path);
+
+    fs.createReadStream(file_path)
+      .pipe(unzipper.Parse())
+      .on('entry', async (entry) => {
+        const fileName = entry.path;
+        const type = entry.type;
+        const size = entry.vars.uncompressedSize;
+        const ext = path.extname(fileName).toLowerCase();
+
+        if (fileName.startsWith('__MACOSX/')) {
+          return;
+        }
+
+        let new_file_id = path.basename(fileName);
+
+        if (doc.drive_type !== 'studio') {
+          new_file_id = 'drv_' + app_id_master + '_' + (await _common.xuda_get_uuid(doc.drive_type)) + ext;
+        }
+
+        const folder_name = 'drive_folder_' + (doc.drive_type === 'studio' ? path.basename(fileName) : _utils.UUID());
+
+        let dir = path.dirname(fileName);
+        if (dir && dir !== '.') {
+          dir = 'drive_folder_' + dir;
+        }
+
+        const file_doc_id = type === 'Directory' ? folder_name : new_file_id;
+        const extract_path = path.join(extract_dir, dir, file_doc_id);
+
+        if (type === 'Directory') {
+          fs.mkdirSync(extract_path, { recursive: true });
+        } else {
+          entry.pipe(fs.createWriteStream(extract_path));
+        }
+
+        const validation_ret = file_upload_validator(fileName);
+
+        let file_doc = {
+          _id: file_doc_id,
+
+          docType: `${doc.drive_type}_drive`,
+          stat: 3,
+          server_file_name: file_doc_id,
+          type: type.toLowerCase(),
+          uid: uid,
+          app_id: app_id_reference,
+          app_id_reference: app_id_master,
+          date_created: Date.now(),
+          date_modified: 0,
+          ip: headers['cf-connecting-ip'],
+          country: headers['cf-ipcountry'],
+          file_ext: ext,
+          is_archive: validation_ret.valid && validation_ret.category === 'archive' ? true : false,
+          size,
+        };
+        if (type === 'Directory') {
+          file_doc.folder_name = path.basename(fileName);
+        } else {
+          file_doc.originalname = new_file_id;
+        }
+
+        try {
+          await db_module.save_app_couch_doc(app_id_reference, file_doc);
+        } catch (error) {}
+      })
+      .on('close', () => {
+        console.log('Extraction complete.');
+      })
+      .on('error', (error) => {
+        console.error('An error occurred:', error);
+      });
+  } catch (err) {
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+
+  return {
+    code: 200,
+    data: '',
+  };
+};
+
+const file_exists = async (file_path) => {
+  return await fs_module.file_exists(file_path);
+};
+const create_directory = async (file_path, permission) => {
+  return await fs_module.mkdir(file_path, permission);
+};
+
+export const delete_file_bulk = async (req) => {
+  if (typeof req.server_files !== 'object') {
+    return {
+      code: -1,
+      data: 'error - server_files must be defined as array',
+    };
+  }
+
+  for await (const val of req.server_files) {
+    await fs_module.delete_file(req.app_id, val, req);
+  }
+
+  return { code: 1, data: req.server_files };
+};
+
+export const upload_drive_file = async (req, job_id, headers = {}, file_obj) => {
+  try {
+    const { drive_type, app_id, make_public, tags = '', is_system, path: file_path } = req;
+    // uid comes from the authenticated token (token_ret), not the client body —
+    // multipart uploads (raw fetch FormData) can't rely on axios_ajax injecting
+    // it, and trusting a client-sent uid would be spoofable. Fall back to an
+    // explicit req.uid for internal callers (e.g. profile-image upload).
+    const uid = req.uid || req.token_ret?.data?.uid;
+    if (!uid) throw new Error('not authorized (no uid)');
+
+    /// validations
+    validate_drive_type(drive_type);
+    if (!file_obj?.['originalname']) {
+      throw new Error('file data missing');
+    }
+
+    const ext = path.extname(file_obj.originalname).toLowerCase();
+    let originalname = path.basename(file_obj.originalname);
+    const tempPath = file_obj.path;
+
+    const validation_ret = file_upload_validator(file_obj.originalname);
+
+    if (!validation_ret.valid) {
+      await fs_module.unlink(tempPath);
+      throw new Error(`File not allowed!`);
+      // throw new Error(`Only ${_conf.allowedExts_drive.toString()} files are allowed!`);
+    }
+
+    let ref, file_name, target_file, save_ret;
+
+    const fsPromises = fs.promises;
+    const stat = await fsPromises.stat(tempPath);
+
+    let tags_arr = [];
+    try {
+      if (!_.isEmpty(tags)) {
+        if (typeof tags === 'string') {
+          tags_arr = tags.split(',');
+        } else if (_.isArray(tags)) {
+          tags_arr = tags;
+        }
+      }
+    } catch (error) {}
+
+    const ts = Date.now();
+    let doc = {
+      docType: `${drive_type}_drive`,
+      stat: 3,
+      originalname,
+      uid,
+      type: 'file',
+      date_created: ts,
+      date_modified: ts,
+      ip: headers['cf-connecting-ip'],
+      country: headers['cf-ipcountry'],
+      file_ext: ext,
+      is_archive: validation_ret.valid && validation_ret.category === 'archive' ? true : false,
+      drive_type,
+      mime: file_obj.mimetype,
+      ocr_stat: ['image', 'application', 'text'].includes(file_obj.mimetype.split('/')[0]) ? 1 : 0,
+      target_file,
+      file_path: file_path || '/',
+      size: stat.isFile() ? stat.size : 0,
+      public: make_public,
+      tags: tags_arr,
+      is_system,
+    };
+    doc = { ...doc, ...(await get_file_info(tempPath)) };
+
+    let check_req = {
+      app_id,
+      uid,
+      drive_type,
+      file_path: path.join(doc.file_path, originalname),
+      type: 'file',
+    };
+    const check_existing_file_ret = await check_drive_file(check_req);
+
+    if (check_existing_file_ret.code < 0) {
+      const rename_file_name = async (i) => {
+        if (i > 1000) {
+          return { code: -1, data: 'too many retries renaming existing file' };
+        }
+
+        const parsed = path.parse(originalname);
+        const baseName = parsed.name;
+        const extension = parsed.ext;
+
+        let tmp_originalname = `${baseName} (${i})${extension}`;
+
+        check_req.file_path = path.join(doc.file_path, tmp_originalname);
+
+        const re_check_res = await check_drive_file(check_req);
+        if (re_check_res.code < 0) {
+          return await rename_file_name(i + 1);
+        }
+        return { code: 1, data: tmp_originalname };
+      };
+      const rename_ret = await rename_file_name(1);
+      if (rename_ret.code < 0) {
+        return rename_ret;
+      }
+      doc.originalname = rename_ret.data;
+      originalname = rename_ret.data;
+    }
+
+    switch (drive_type) {
+      case 'studio': {
+        ref = await _common.get_project_app_id(req.app_id, true);
+        const target_dir = path.join(_conf[`studio_drive_path`], ref);
+        file_name = path.join(file_path, doc.originalname);
+
+        target_file = path.join(target_dir, file_name);
+
+        if (!(await fs_module.file_exists(target_dir))) {
+          await fs_module.mkdir(target_dir, 0o775, true);
+        }
+        if (await fs_module.file_exists(target_file)) {
+          return {
+            code: -762,
+            data: `file already exist`,
+          };
+        }
+
+        await fs_module.copy(tempPath, target_file);
+        doc.server_file_name = file_name;
+
+        doc.app_id = app_id;
+        doc.app_id_reference = ref;
+
+        doc._id = file_name;
+
+        save_ret = await db_module.save_app_couch_doc(ref, doc);
+        misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id);
+        break;
+      }
+      case 'workspace': {
+        ref = await _common.get_project_app_id(req.app_id, true);
+        file_name = 'drv_' + ref + '_' + (await _common.xuda_get_uuid(drive_type)) + ext;
+
+        if (file_obj.originalname.includes(`drv_${ref}`)) {
+          file_name = file_obj.originalname;
+        }
+
+        doc.server_file_name = file_name;
+
+        doc.app_id = app_id;
+        doc.app_id_reference = ref;
+
+        const { data: app_obj } = await db_module.get_app_obj(app_id);
+        if (app_obj?.app_type === 'datacenter') {
+          const host = `root@${app_obj.app_hosting_server.ip}`;
+          await _utils.run_ssh_script(`scp ${tempPath} ${host}:/var/xuda/workspace_drive/${file_name}; `);
+        } else if (app_obj?.is_deployment) {
+          const { data: datacenter_obj } = await db_module.get_app_obj(app_obj.app_datacenter_id);
+          const host = `root@${datacenter_obj.app_hosting_server.ip}`;
+          await _utils.run_ssh_script(`scp ${tempPath} ${host}:/var/xuda/workspace_drive/${file_name}; `);
+        } else {
+          doc.bucket = {
+            [`${process.env.XUDA_HOSTNAME}`]: await upload_file_to_spaces(tempPath, ref, drive_type, file_name),
+          };
+        }
+        doc._id = file_name;
+        save_ret = await db_module.save_app_couch_doc(await _common.get_project_app_id(req.app_id), doc);
+        break;
+      }
+      case 'user': {
+        ref = await get_account_default_project_id(uid);
+        file_name = 'drv_' + ref + '_' + (await _common.xuda_get_uuid(drive_type)) + ext;
+
+        doc.server_file_name = file_name;
+
+        doc.bucket = {
+          [`${process.env.XUDA_HOSTNAME}`]: await upload_file_to_spaces(tempPath, ref, drive_type, file_name),
+        };
+        doc._id = file_name;
+        save_ret = await save_user_drive_file(uid, doc);
+        break;
+      }
+
+      default:
+        break;
+    }
+
+    let file_url = get_file_url(drive_type, file_name, ref);
+
+    await fs_module.unlink(tempPath);
+
+    return {
+      code: 760,
+      data: {
+        server_file_name: file_name,
+        filename: file_obj.originalname,
+        file_url,
+        file_path,
+      },
+      rename: check_existing_file_ret < 0,
+    };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+const check_single_drive_file = async (req, job_id, headers, file_obj) => {
+  const { type = 'file', drive_type, app_id, uid, file_path, folder_name } = req;
+
+  let master_app_id;
+
+  if (['studio', 'workspace'].includes(drive_type)) {
+    master_app_id = await _common.get_project_app_id(app_id, true);
+  }
+
+  let selector = {
+    type,
+    file_path: path.dirname(file_path),
+    stat: 3,
+  };
+
+  if (type === 'file') {
+    selector.originalname = path.basename(file_path);
+  }
+  if (type === 'directory') {
+    selector.file_path = file_path;
+    selector.folder_name = folder_name;
+  }
+
+  switch (drive_type) {
+    case 'studio': {
+      const target_dir = path.join(_conf[`studio_drive_path`], master_app_id);
+
+      let target_file = path.join(target_dir, file_path);
+      if (type === 'directory') {
+        target_file = path.join(target_dir, file_path, folder_name);
+      }
+
+      if (await fs_module.file_exists(target_file)) {
+        return {
+          code: -764,
+          data: `${type} exist`,
+        };
+      }
+
+      break;
+    }
+    case 'workspace': {
+      selector.docType = 'workspace_drive';
+      const workspace_drive_res = await db_module.find_app_couch_query(app_id, {
+        selector,
+        limit: 99,
+      });
+      if (workspace_drive_res.docs.length) {
+        return {
+          code: -764,
+          data: `${type} exist`,
+          duplicates: workspace_drive_res.docs,
+        };
+      }
+
+      break;
+    }
+    case 'user': {
+      selector.docType = 'user_drive';
+
+      // const user_drive_res = await find_contact_query(uid, {
+      //   selector,
+      //   limit: 99,
+      // });
+      const app_id = await get_account_default_project_id(uid);
+      const user_drive_res = await db_module.find_app_couch_query(app_id, {
+        selector,
+        limit: 99,
+      });
+
+      if (user_drive_res.docs.length) {
+        return {
+          code: -764,
+          data: `${type} exist`,
+          duplicates: user_drive_res.docs,
+        };
+      }
+
+      break;
+    }
+
+    default:
+      return {
+        code: -764,
+        data: 'invalid method',
+      };
+  }
+
+  return {
+    code: 764,
+    data: 'ok',
+  };
+};
+
+export const check_drive_files = async (req, job_id, headers, file_obj) => {
+  const files = req.files ||
+    req.file_paths?.map((curr_file_path) => ({
+      file_path: curr_file_path,
+    })) || [
+      {
+        file_path: req.file_path,
+        folder_name: req.folder_name,
+        type: req.type,
+      },
+    ];
+
+  const results = [];
+
+  for (const item of files) {
+    results.push(
+      await check_single_drive_file(
+        {
+          ...req,
+          ...item,
+        },
+        job_id,
+        headers,
+        file_obj,
+      ),
+    );
+  }
+
+  const duplicates = results.flatMap((item) => item?.duplicates || []);
+  const has_duplicates = results.some((item) => item?.code < 0);
+
+  return {
+    code: has_duplicates ? -764 : 764,
+    data: has_duplicates ? 'one or more files exist' : 'ok',
+    files: results,
+    duplicates,
+  };
+};
+
+export const check_drive_file = async (req, job_id, headers, file_obj) => {
+  const ret = await check_drive_files(req, job_id, headers, file_obj);
+
+  if (!ret.files?.length) {
+    return {
+      code: -764,
+      data: 'no files to check',
+      duplicates: [],
+    };
+  }
+
+  return ret.files[0];
+};
+
+const ocr_drive_file = async (app_id, doc) => {
+  const { drive_type, uid, file_path, originalname } = doc;
+
+  let target_file = get_file_url(drive_type, path.join(file_path, doc._id), app_id || uid);
+
+  function addQueryParam(urlString, key, value) {
+    const parsedUrl = new url.URL(urlString);
+    parsedUrl.searchParams.set(key, value);
+    return parsedUrl.toString();
+  }
+
+  target_file = addQueryParam(target_file, 'xuda_internal_request_code', _conf.xuda_internal_request_code);
+
+  let save_ret;
+  try {
+    doc.ocr_stat = 2;
+    doc.ocr_stat_date = Date.now();
+    save_ret = await save_drive_doc(drive_type, uid, app_id, doc, file_path);
+
+    doc = await get_drive_doc('file', drive_type, app_id, uid, path.join(file_path, originalname));
+
+    let ocr = '';
+
+    function detectLanguageByCountry(cfCountry) {
+      const countryData = countryLanguage.getCountry(cfCountry);
+      let lang = 'eng';
+      if (countryData && countryData.languages && countryData.languages.length > 0) {
+        for (let language of countryData.languages) {
+          lang += `+${language.iso639_2}`;
+        }
+      }
+      return lang;
+    }
+
+    let lang = detectLanguageByCountry(doc.country);
+
+    const generalConfig = { oem: 1, psm: 3, lang };
+
+    switch (doc.mime.split('/')[0]) {
+      case 'image': {
+        ocr = await tesseract.recognize(target_file, generalConfig);
+
+        break;
+      }
+
+      case 'application': {
+        switch (doc.mime.split('/')[1]) {
+          case 'pdf': {
+            const images = await convertPDF(target_file);
+            for await (const imageData of images) {
+              ocr += await tesseract.recognize(imageData.path, generalConfig);
+            }
+            break;
+          }
+
+          case 'vnd.openxmlformats-officedocument.wordprocessingml.document': {
+            ocr = (await mammoth.extractRawText({ path: target_file })).value;
+            break;
+          }
+
+          case 'nd.ms-excel':
+          case 'vnd.openxmlformats-officedocument.spreadsheetml.sheet': {
+            const sheets = xlsx.parse(target_file);
+            sheets.forEach((sheet) => {
+              console.log(`Sheet: ${sheet.name}`);
+              sheet.data.forEach((row) => {
+                ocr += row.join(' ');
+              });
+            });
+            break;
+          }
+
+          case 'vnd.ms-powerpoint':
+          case 'vnd.openxmlformats-officedocument.presentationml.presentation':
+            // tbd
+            break;
+
+          default:
+            ocr = (await fs_module.read_file(target_file)).data;
+            break;
+        }
+        break;
+      }
+
+      case 'text': {
+        ocr = (await fs_module.read_file(target_file)).data;
+        break;
+      }
+
+      default:
+        break;
+    }
+
+    doc.ocr = ocr
+      .replace(/<\/?[^>]+(>|$)/g, '')
+      .replace(/[\n]/g, ' ')
+      .replace(/[\f\t]/g, '');
+    doc.ocr_lang = lang;
+    doc.ocr_stat = 3;
+  } catch (err) {
+    doc.ocr_stat = 4;
+    doc.ocr_error = err.message;
+  } finally {
+    doc.ocr_stat_ts = Date.now();
+
+    save_ret = await save_drive_doc(drive_type, uid, app_id, doc, file_path);
+  }
+};
+
+const validate_drive_type = (drive_type) => {
+  if (!['studio', 'workspace', 'user'].includes(drive_type)) {
+    throw new Error('error - drive_type values allowed: studio, workspace or users');
+  }
+};
+
+export const run_drive_pending_ocr = async () => {
+  try {
+    let selector = {
+      docType: 'app',
+      app_status_code: {
+        $eq: 3,
+      },
+      $or: [
+        {
+          app_type: 'master',
+        },
+        {
+          app_type: 'instance',
+        },
+        {
+          app_type: 'datacenter',
+        },
+      ],
+    };
+
+    const app_opt = {
+      selector,
+      limit: 99999,
+    };
+
+    let app_res = await db_module.find_couch_query('xuda_master', app_opt);
+
+    for (let app of app_res.docs) {
+      let opt = {
+        selector: { docType: 'user_drive', ocr_stat: 1, stat: 3 },
+        limit: 1,
+      };
+
+      const user_drive_res = await db_module.find_app_couch_query(app._id, opt);
+      for await (let doc of user_drive_res.docs) {
+        await ocr_drive_file(null, doc);
+      }
+
+      opt.selector.docType = 'workspace_drive';
+      const app_drive_res = await db_module.find_app_couch_query(app._id, opt);
+      for await (let doc of app_drive_res.docs) {
+        await ocr_drive_file(app._id, doc);
+      }
+    }
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+const _drive_size_cache = new Map();
+const _DRIVE_SIZE_TTL_MS = 30 * 60 * 1000;
+
+export const get_drive_size = async (req) => {
+  try {
+    const { drive_type, app_id, uid } = req;
+    const cache_key = `${drive_type}|${app_id || ''}|${uid || ''}`;
+    const cached = _drive_size_cache.get(cache_key);
+    if (cached && Date.now() - cached.ts < _DRIVE_SIZE_TTL_MS) {
+      return { code: 200, data: cached.size };
+    }
+
+    let size = 0;
+    let app_id_master, directoryPath;
+    switch (drive_type) {
+      case 'user':
+        directoryPath = '';
+        break;
+      case 'workspace':
+        directoryPath = '';
+        app_id_master = await _common.get_project_app_id(app_id, true);
+        break;
+      default:
+        app_id_master = await _common.get_project_app_id(app_id, true);
+        directoryPath = path.join(_conf[`${drive_type}_drive_path`], app_id_master, '/');
+        break;
+    }
+
+    size = await get_folder_size(directoryPath, drive_type, app_id_master, uid);
+    if (drive_type === 'workspace') {
+      size += await get_folder_size(directoryPath, drive_type, app_id);
+    }
+
+    _drive_size_cache.set(cache_key, { size, ts: Date.now() });
+    return { code: 200, data: size };
+  } catch (err) {
+    return { code: -200, data: err.message };
+  }
+};
+
+// --- Object storage (S3 / R2) helpers ------------------------------------
+// Credentials: prefer R2 (post-migration), fall back to DO Spaces so the same
+// code runs before and after the cutover.
+const _storage_credentials = () => {
+  if (_conf.r2?.access_key_id && _conf.r2?.secret_access_key) {
+    return { accessKeyId: _conf.r2.access_key_id, secretAccessKey: _conf.r2.secret_access_key };
+  }
+  return {
+    accessKeyId: _conf.digitalocean?.spaces_access_key,
+    secretAccessKey: _conf.digitalocean?.spaces_secret_key,
+  };
+};
+
+// R2 addresses buckets path-style against the account endpoint; DO Spaces uses
+// virtual-hosted style.
+const _is_r2 = () => !!(_conf.r2?.access_key_id);
+
+// Public URL for a stored object, ALWAYS rebuilt from the Key. Post-migration
+// every bucket is served from one custom domain (r2.public_base); pre-migration
+// we reconstruct the virtual-hosted DO Spaces URL. Rebuilding from the Key means
+// existing docs that still carry old DO Locations resolve to the live backend.
+const _public_url_for = (region_host, key) => {
+  const k = String(key || '').replace(/^\/+/, '');
+  if (!k) return null;
+  if (_conf.r2?.public_base) return `${String(_conf.r2.public_base).replace(/\/+$/, '')}/${k}`;
+  const conf = _conf.storage_bucket?.[region_host];
+  if (!conf) return null;
+  const host = String(conf.endpoint || '').replace(/^https?:\/\//, '').replace(/\/+$/, '');
+  return host ? `https://${conf.name}.${host}/${k}` : null;
+};
+
+const upload_file_to_spaces = async (tempPath, ref, drive_type, file_name) => {
+  const region_host = process.env.XUDA_HOSTNAME;
+  const conf = _conf.storage_bucket?.[region_host];
+  const s3 = _drive_s3_for(region_host);
+  if (!s3 || !conf) {
+    console.error('upload_file_to_spaces: no storage config for', region_host);
+    return;
+  }
+  const Bucket = conf.name;
+  const Key = path.join(region_host, drive_type, ref, _utils.UUID() + '_' + file_name);
+
+  try {
+    const upload = new Upload({
+      client: s3,
+      params: { Bucket, Key, Body: fs.createReadStream(tempPath), ContentType: _drive_content_type_for(file_name) },
+    });
+
+    const data = await upload.done();
+    // Override the SDK Location with the canonical public URL (custom domain on
+    // R2), and pin Bucket/Key so the stored doc.bucket entry is backend-correct.
+    return { ...data, Location: _public_url_for(region_host, Key), Bucket, Key, key: Key };
+  } catch (err) {
+    console.error('Error', err);
+  }
+};
+
+// Retired under the single R2 namespace: every region resolves to the same
+// bucket, so there is nothing to copy. Kept as a no-op so existing callers keep
+// working — returns a backend-correct location rebuilt from the Key.
+export const copy_file_to_another_bucket = async (source_region, target_region, file_name) => {
+  return {
+    code: 1,
+    data: {
+      Location: _public_url_for(target_region, file_name),
+      key: file_name,
+      Key: file_name,
+      Bucket: _conf.storage_bucket?.[target_region]?.name,
+    },
+  };
+};
+
+const get_folder_size = async (dir, drive_type, app_id, uid) => {
+  let totalSize = 0;
+
+  const calculateSizeFs = async (dirPath) => {
+    let entries;
+    try {
+      entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    } catch (err) {
+      return;
+    }
+    const subdirs = [];
+    const file_stats = [];
+    for (const entry of entries) {
+      const childPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        subdirs.push(childPath);
+      } else if (entry.isFile()) {
+        file_stats.push(
+          fs.promises
+            .stat(childPath)
+            .then((s) => {
+              totalSize += s.size;
+            })
+            .catch(() => {}),
+        );
+      }
+    }
+    await Promise.all(file_stats);
+    for (const d of subdirs) {
+      await calculateSizeFs(d);
+    }
+  };
+
+  const calculateSizeDocs = async (dirPath) => {
+    let opt = {
+      selector: {
+        docType: `${drive_type}_drive`,
+        stat: 3,
+        file_path: path.join('/', dirPath),
+      },
+      limit: 99999,
+    };
+    let ret;
+    if (drive_type === 'user') {
+      // opt.selector.uid = uid;
+
+      const app_id = await get_account_default_project_id(uid);
+      ret = await db_module.find_app_couch_query(app_id, opt);
+    } else {
+      ret = await db_module.find_app_couch_query(app_id, opt);
+    }
+
+    for await (let doc of ret.docs) {
+      if (doc.type === 'directory') {
+        await calculateSizeDocs(path.join('/', doc._id));
+      } else {
+        totalSize += doc.size || 0;
+      }
+    }
+  };
+
+  if (['user', 'workspace'].includes(drive_type)) {
+    await calculateSizeDocs(dir);
+  } else {
+    await calculateSizeFs(dir);
+  }
+  return totalSize;
+};
+
+const get_file_info = async (file_path) => {
+  let doc = {};
+  doc.exif_ret = await fs_module.get_exif(file_path);
+  try {
+    const dimensions = imageSize(file_path);
+    doc.dimensions = `${dimensions.width}x${dimensions.height}`;
+  } catch (error) {}
+  return doc;
+};
+
+export const delete_file_from_bucket = async (bucket) => {
+  try {
+    for await (let [region_host, val] of Object.entries(bucket || {})) {
+      const Key = val?.key || val?.Key;
+      if (!Key) continue;
+      // Resolve the client + bucket NAME from config for the file's region (fall
+      // back to this server's region). Never trust the stored val.Bucket — after
+      // the R2 cutover that name (e.g. xuda-bucket-nyc) no longer exists.
+      const s3 = _drive_s3_for(region_host) || _drive_s3_for(process.env.XUDA_HOSTNAME);
+      const Bucket = _conf.storage_bucket?.[region_host]?.name || _conf.storage_bucket?.[process.env.XUDA_HOSTNAME]?.name;
+      if (!s3 || !Bucket) continue;
+      await s3.send(new DeleteObjectCommand({ Bucket, Key }));
+    }
+  } catch (err) {
+    console.error('Error', err);
+  }
+};
+
+export const update_drive_file_tags = async (req, job_id, headers) => {
+  try {
+    const { type, drive_type, app_id, uid, file_path, tags = [] } = req;
+
+    validate_drive_type(drive_type);
+
+    let doc = await get_drive_doc(type, drive_type, app_id, uid, file_path, headers);
+
+    doc.date_modified = Date.now();
+    doc.tags = tags;
+
+    return await save_drive_doc(drive_type, uid, app_id, doc);
+  } catch (err) {
+    return {
+      code: -200,
+      data: err.message,
+    };
+  }
+};
+
+const get_file_url = (drive_type, file_name, ref) => {
+  let file_url = `https://${process.env.XUDA_HOSTNAME}/${drive_type}-drive/${ref}${file_name?.substr(0, 1) !== '/' ? '/' : ''}${file_name}`;
+  return file_url;
+};
+
+const get_drive_doc = async (type, drive_type, app_id, uid, file_path, headers) => {
+  let check_req = {
+    app_id,
+    uid,
+    drive_type,
+    file_path: type === 'file' ? file_path : path.dirname(file_path),
+    folder_name: type === 'directory' ? path.basename(file_path) : '',
+    type,
+  };
+  const check_existing_file_ret = await check_drive_file(check_req);
+
+  if (!check_existing_file_ret?.duplicates && drive_type !== 'studio') {
+    throw new Error(`${file_path} document not found`);
+  }
+
+  let doc_ret;
+  let doc;
+  switch (drive_type) {
+    case 'studio': {
+      const app_id_reference = await _common.get_project_app_id(app_id);
+      doc_ret = await db_module.get_app_couch_doc(app_id_reference, file_path);
+      break;
+    }
+    case 'user':
+      doc_ret = await get_user_drive_file(uid, check_existing_file_ret.duplicates[0]._id);
+      break;
+
+    case 'workspace': {
+      const app_id_reference = await _common.get_project_app_id(app_id);
+      const app_id_master = await _common.get_project_app_id(app_id, true);
+
+      doc_ret = await db_module.get_app_couch_doc(app_id_reference, check_existing_file_ret.duplicates[0]._id);
+
+      if (doc_ret?.data?.type === 'file' && !doc_ret?.data?._id.includes(app_id) && !doc_ret?.data?._id.includes(app_id_master)) {
+        throw new Error('file_path unauthorized');
+      }
+
+      break;
+    }
+    default:
+      break;
+  }
+
+  if (doc_ret.code < 0) {
+    if (drive_type === 'studio') {
+      const app_id_reference = await _common.get_project_app_id(app_id);
+      const file_name = path.basename(file_path);
+      const ext = path.extname(file_name).toLowerCase();
+      const internal_file_path = path.join(_conf.studio_drive_path, app_id_reference, file_path);
+      const statsObj = fs.statSync(internal_file_path);
+      const validation_ret = file_upload_validator(file_name);
+      doc = {
+        _id: file_path,
+        docType: `studio_drive`,
+        stat: 3,
+        server_file_name: file_name,
+        originalname: file_name,
+        file_path: file_path,
+        date_created: new Date(statsObj.birthtime).valueOf(),
+        date_modified: 0,
+        ip: headers?.['cf-connecting-ip'],
+        country: headers?.['cf-ipcountry'],
+        file_ext: ext,
+        is_archive: validation_ret.valid && validation_ret.category === 'archive' ? true : false,
+        drive_type,
+        app_id: await _common.get_project_app_id(app_id),
+        app_id_reference: await _common.get_project_app_id(app_id, true),
+        uid,
+      };
+      const save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+      if (save_ret.code < 0) {
+        throw new Error('studio file doc save error');
+      }
+      doc._rev = save_ret.data.rev;
+    } else {
+      throw new Error('file doc not found');
+    }
+  } else {
+    doc = doc_ret.data;
+  }
+
+  return doc;
+};
+
+const save_drive_doc = async (drive_type, uid, app_id, doc) => {
+  let save_ret;
+
+  switch (drive_type) {
+    case 'workspace':
+    case 'studio':
+      const app_id_reference = await _common.get_project_app_id(app_id);
+      save_ret = await db_module.save_app_couch_doc(app_id_reference, doc);
+      break;
+
+    case 'user':
+      save_ret = await save_user_drive_file(uid, doc);
+      break;
+
+    default:
+      break;
+  }
+
+  if (save_ret.code < 0) {
+    throw new Error(save_ret.data);
+  }
+
+  return save_ret;
+};
+
+// Stable hash of a script's source. Lets each server detect when its locally-built
+// dist is stale vs the current scriptData.value, so a changed script recompiles (and
+// re-rsyncs to datacenters) instead of being skipped just because vite_build_res exists.
+export const js_src_hash = (s) => {
+  s = String(s || '');
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h.toString(36) + '.' + s.length;
+};
+
+export const compile_javascript_program_in_studio_drive = async (req, job_id) => {
+  const { app_id, doc } = req;
+
+  try {
+    const studio_drive_script_folder = path.join(_conf.studio_drive_path, app_id, 'scripts');
+    const fs_module = await import(`${module_path}/fs_module/index.mjs`);
+    if (!(await fs_module.file_exists(studio_drive_script_folder))) {
+      await fs_module.mkdir(studio_drive_script_folder, 0o775);
+    }
+
+    const studio_drive_script_program_folder = path.join(studio_drive_script_folder, doc._id);
+
+    const src = path.join(studio_drive_script_program_folder, 'src');
+    const dist = path.join(studio_drive_script_program_folder, 'dist');
+
+    if (!(await fs_module.file_exists(studio_drive_script_program_folder))) {
+      await fs_module.mkdir(studio_drive_script_program_folder, 0o775);
+      await fs_module.mkdir(src, 0o775);
+      await fs_module.mkdir(dist, 0o775);
+    }
+
+    const inputCode = doc.scriptData?.value || '';
+
+    function wrapCodeWithFunction(inputCode) {
+      const lines = inputCode.split('\n');
+      const importLines = [];
+      const codeLines = [];
+
+      for (const line of lines) {
+        if (line.trim().startsWith('import ')) {
+          importLines.push(line);
+        } else {
+          codeLines.push(line);
+        }
+      }
+
+      const wrappedCode = [...importLines, '', 'export default async function (params,xu, SESSION_ID, SESSION_OBJ, job_id) {', ...codeLines.map((line) => `  ${line}`), '}'];
+
+      return wrappedCode.join('\n');
+    }
+
+    let content = wrapCodeWithFunction(inputCode);
+    const index_css = path.join(dist, 'index.css');
+    if (await fs_module.file_exists(index_css)) {
+      content = ` export const css = true  \n` + content;
+    }
+
+    const getLocalPackageName = (doc) => {
+      const rawName = doc?._id || doc?.properties?.menuName || 'program';
+      const safeName = String(rawName)
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, '-')
+        .replace(/^[._-]+|[._-]+$/g, '');
+      const packageName = `xuda-js-program-${safeName || 'program'}`.slice(0, 214);
+
+      return packageName.replace(/[._-]+$/g, '') || 'xuda-js-program';
+    };
+
+    const index_js = path.join(src, 'index.mjs');
+    await fs_module.save_file(index_js, content);
+
+    let packageJSON = {
+      name: getLocalPackageName(doc),
+      version: '1.0.0',
+      description: '',
+      main: 'index.js',
+      scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' },
+      license: 'ISC',
+      dependencies: {},
+      devDependencies: { vite: '^5.4.10' },
+      author: doc?.studio_meta?.checkedInUserName || doc?.studio_meta?.createdByUid || '',
+    };
+    const package_json = path.join(studio_drive_script_program_folder, 'package.json');
+
+    const importRegex = /import\s+(?:.*?from\s+)?['"](.+?)['"]/g;
+    const requireRegex = /require\(['"](.+?)['"]\)/g;
+
+    let devDependencies = packageJSON.devDependencies || {};
+    let allDependencies = new Set();
+    let externalImports = new Set();
+
+    const isUrlSpecifier = (specifier) => /^[a-z][a-z0-9+.-]*:/i.test(specifier) || specifier.startsWith('//');
+
+    const getPackageDependencyName = (specifier) => {
+      if (!specifier) {
+        return;
+      }
+
+      if (isUrlSpecifier(specifier)) {
+        externalImports.add(specifier);
+        return;
+      }
+
+      if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('#') || specifier.endsWith('.css')) {
+        return;
+      }
+
+      if (specifier.startsWith('@')) {
+        const [scope, packageName] = specifier.split('/');
+        return scope && packageName ? `${scope}/${packageName}` : undefined;
+      }
+
+      return specifier.split('/')[0];
+    };
+
+    const extractDependencies = (fileContent, regex) => {
+      const matches = [];
+      let match;
+      regex.lastIndex = 0;
+      while ((match = regex.exec(fileContent)) !== null) {
+        const dep = getPackageDependencyName(match[1]);
+        if (dep) {
+          matches.push(dep);
+        }
+      }
+      return matches;
+    };
+
+    const imports = extractDependencies(content, importRegex);
+    const requires = extractDependencies(content, requireRegex);
+    imports.concat(requires).forEach((dep) => allDependencies.add(dep));
+
+    for await (const dep of allDependencies) {
+      if (!devDependencies[dep]) {
+        console.log(`Adding dependency: ${dep}`);
+        // const npm_ret = await getPackageManifest({
+        //   name: dep,
+        // });
+
+        const npm_ret = await getPackageManifest(dep);
+        devDependencies[dep] = npm_ret.version;
+      }
+    }
+    for (const [key, val] of Object.entries(doc?.scriptData?.dependencies || {})) {
+      devDependencies[key] = val;
+    }
+
+    packageJSON.devDependencies = devDependencies;
+
+    await fs_module.save_file(package_json, JSON.stringify(packageJSON, null, 2));
+
+    const vite_config = path.join(studio_drive_script_program_folder, 'vite.config.js');
+
+    const code = `
+    
+export default {
+  build: {
+    lib: {
+      entry: "src/index.mjs",
+      formats: ["es"],
+      name: "MyLibrary", // Global variable for UMD/IIFE formats
+    },
+    rollupOptions: {
+      external: ${JSON.stringify(Array.from(externalImports))},
+      output: {
+        manualChunks(id) {
+          if (id.includes("node_modules")) {
+            return "vendor";
+          }
+
+        },
+        entryFileNames: "[name].mjs",
+        chunkFileNames: "[name]-[hash].mjs",
+        assetFileNames: (assetInfo) => {
+          if (assetInfo.name && assetInfo.name.endsWith(".css")) {
+            return "index[extname]";
+          }
+          return "[name]-[hash][extname]";
+        },
+    
+        
+      },
+    },
+    minify: false, // Disable minification for easier debugging
+  },
+  
+  define: {
+    "process.env": process.env, // Pass environment variables
+  },
+};
+
+
+  
+  `;
+
+    await fs_module.save_file(vite_config, code);
+
+    await _utils.run_ssh_script(`npm i --prefix ${studio_drive_script_program_folder};`);
+    const build_ret = await _utils.run_ssh_script(`npm run build --prefix ${studio_drive_script_program_folder};`);
+
+    misc_msa.rsync_drive_resources_to_remote_servers('studio', app_id);
+    const vite_build_res = {
+      code: 1,
+      src_hash: js_src_hash(inputCode),
+      data: {
+        build_ret,
+        dependencies: devDependencies,
+      },
+    };
+    if (job_id) {
+      return vite_build_res;
+    }
+
+    doc.vite_build_res = vite_build_res;
+    doc.scriptData.dependencies = devDependencies;
+
+    db_module.save_app_couch_doc(app_id, doc);
+  } catch (err) {
+    doc.vite_build_res = {
+      code: -1,
+      data: err.message,
+    };
+    console.error(doc);
+    if (job_id) {
+      return doc.vite_build_res;
+    }
+    db_module.save_app_couch_doc(app_id, doc);
+  }
+};
+
+export const update_drive_addons = async (req, job_id) => {
+  const { drive_type, app_id, uid, ocr, image_convertor, video_ai, ai_component_generator, edit_image } = req;
+
+  const set_drive_addons = (drive_addons) => {
+    if (typeof ocr !== 'undefined') {
+      drive_addons.ocr = ocr;
+    }
+
+    if (typeof image_convertor !== 'undefined') {
+      drive_addons.image_convertor = image_convertor;
+    }
+
+    if (typeof video_ai !== 'undefined') {
+      drive_addons.video_ai = video_ai;
+    }
+
+    if (typeof ai_component_generator !== 'undefined') {
+      drive_addons.ai_component_generator = ocr;
+    }
+
+    if (typeof edit_image !== 'undefined') {
+      drive_addons.edit_image = edit_image;
+    }
+  };
+
+  let drive_addons = {};
+  let save_ret;
+  if (drive_type === 'workspace' || drive_type === 'studio') {
+    const master_id = await _common.get_project_app_id(app_id, true);
+    let app_obj_ret = await db_module.get_app_obj(master_id);
+    if (app_obj_ret.data.drive_addons) {
+      drive_addons = app_obj_ret.data.drive_addons;
+    }
+    set_drive_addons(drive_addons);
+    save_ret = await db_module.save_app_couch_doc2(master_id, app_obj_ret.data);
+  }
+  if (drive_type === 'user') {
+    let account_ret = await db_module.get_couch_doc('xuda_accounts', uid);
+
+    if (account_ret.data.drive_addons) {
+      drive_addons = account_ret.data.drive_addons;
+    }
+    set_drive_addons(drive_addons);
+    save_ret = await db_module.save_couch_doc('xuda_accounts', account_ret.data);
+  }
+  return save_ret;
+};
+
+export const getExtensionFromUrl = function (imageUrl) {
+  try {
+    // Parse the URL to get the pathname
+    const parsedUrl = new URL(imageUrl);
+    const pathname = parsedUrl.pathname;
+
+    // Get extension from pathname
+    const ext = path.extname(pathname);
+
+    // Remove the dot and convert to lowercase
+    return ext ? ext.toLowerCase().slice(1) : '';
+  } catch (error) {
+    // If URL parsing fails, try to extract extension directly
+    return getExtensionFromString(imageUrl);
+  }
+};
+
+export const get_user_drive_file = async function (uid, filename) {
+  const app_id = await get_account_default_project_id(uid);
+  const drive_ret = await db_module.get_app_couch_doc(app_id, filename);
+  return drive_ret;
+};
+
+// ── Static-site vibe: see + edit the site's source folder directly through the
+// cpi (Spaces + CouchDB) — no temp dir, no server disk growth. The "folder" is
+// the app's static_website.source.folder_path; files live in Spaces, hierarchy
+// in CouchDB. These back the static-site assistant's tools.
+
+const _site_source_folder = async (app_id) => {
+  const ret = await db_module.get_couch_doc('xuda_master', app_id);
+  const a = ret?.data;
+  if (!a || a.app_type !== 'static_website') return null;
+  return a.static_website?.source?.folder_path || null;
+};
+
+// Put bytes to the region bucket + upsert the matching user_drive doc. Reused by
+// write_site_file (assistant edits) and by version restore (override dev folder).
+const _write_user_drive_file = async (uid, project_id, dir, name, buffer, mime) => {
+  const region = process.env.XUDA_HOSTNAME;
+  const Bucket = _conf.storage_bucket?.[region]?.name;
+  const s3 = _drive_s3_for(region);
+  if (!s3 || !Bucket) return { code: -1, data: `no storage bucket for region ${region}` };
+  const existing = await db_module.find_app_couch_query(project_id, {
+    selector: { docType: 'user_drive', type: 'file', stat: 3, file_path: dir, originalname: name },
+    limit: 1,
+  });
+  let doc = existing?.docs?.[0] || null;
+  const ext = path.extname(name).toLowerCase();
+  const Key = doc?.bucket?.[region]?.Key || doc?.bucket?.[region]?.key || `drv_${project_id}_${await _common.xuda_get_uuid('user')}${ext}`;
+  await s3.send(new PutObjectCommand({ Bucket, Key, Body: buffer, ContentType: mime || _drive_content_type_for(name) }));
+  if (doc) {
+    doc.size = buffer.length;
+    doc.date_modified = Date.now();
+    doc.mime = mime || doc.mime || _drive_content_type_for(name);
+    doc.bucket = { ...(doc.bucket || {}), [region]: { Bucket, Key } };
+  } else {
+    doc = {
+      _id: Key,
+      docType: 'user_drive',
+      type: 'file',
+      stat: 3,
+      uid,
+      originalname: name,
+      file_path: dir,
+      file_ext: ext,
+      mime: mime || _drive_content_type_for(name),
+      size: buffer.length,
+      date_created: Date.now(),
+      date_modified: Date.now(),
+      server_file_name: Key,
+      bucket: { [region]: { Bucket, Key } },
+    };
+  }
+  await save_user_drive_file(uid, doc);
+  return { code: 1, data: { Key, size: buffer.length } };
+};
+
+// List the site's source files (paths only — lightweight, no bytes).
+export const list_site_files = async (req) => {
+  try {
+    const { uid } = req || {};
+    let folder = req?.site_folder;
+    if (!folder && req?.app_id) folder = await _site_source_folder(req.app_id);
+    if (!uid || !folder) return { code: -1, data: 'uid + (site_folder or app_id) required' };
+    // Plan A: the source lives on the studio fs — list the real files on disk.
+    const { dir } = await _static_site_fs_dir(uid, folder);
+    if (!fs.existsSync(dir)) return { code: 1, data: { folder, files: [] } };
+    const scan = await fs_module.dree_scan(dir, { stat: true, size: true, depth: 100, symbolicLinks: false, hash: false });
+    const files = [];
+    const walk = (node) => {
+      if (!node) return;
+      if (node.type === 'file') {
+        const rel = node.path.replace(dir, '').replace(/^\/+/, '');
+        if (rel) files.push({ path: rel, size: node.size || 0 });
+      }
+      (node.children || []).forEach(walk);
+    };
+    if (scan.code === 1) walk(scan.data);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { code: 1, data: { folder, files } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Read one source file's text content.
+export const read_site_file = async (req) => {
+  try {
+    const { uid, app_id } = req;
+    const rel = String(req.path || '').replace(/^\/+/, '');
+    if (!uid || !app_id || !rel) return { code: -1, data: 'uid + app_id + path required' };
+    const folder = await _site_source_folder(app_id);
+    if (!folder) return { code: -1, data: 'no source folder for this site' };
+    const full = path.posix.join(folder, rel);
+    const project_id = await get_account_default_project_id(uid);
+    const ret = await db_module.find_app_couch_query(project_id, {
+      selector: { docType: 'user_drive', type: 'file', stat: 3, file_path: path.posix.dirname(full), originalname: path.posix.basename(full) },
+      limit: 1,
+    });
+    const d = ret?.docs?.[0];
+    if (!d) return { code: -1, data: `file not found: ${rel}` };
+    const region = _pick_file_region(d);
+    const b = (region && d.bucket?.[region]) || {};
+    const Bucket = b.Bucket || b.bucket;
+    const Key = b.Key || b.key;
+    const s3 = region ? _drive_s3_for(region) : null;
+    if (!s3 || !Bucket || !Key) return { code: -1, data: 'file bytes unavailable' };
+    const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
+    const buf = await _stream_to_buffer(obj.Body);
+    return { code: 1, data: { path: rel, content: buf.toString('utf8'), size: buf.length } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Write/overwrite one source file. Does NOT publish — the user deploys via the
+// Build modal, so changes are always accepted explicitly.
+export const write_site_file = async (req) => {
+  try {
+    const { uid, app_id } = req;
+    const rel = String(req.path || '').replace(/^\/+/, '');
+    const content = req.content;
+    if (!uid || !app_id || !rel || typeof content !== 'string') return { code: -1, data: 'uid + app_id + path + content (string) required' };
+    const folder = await _site_source_folder(app_id);
+    if (!folder) return { code: -1, data: 'no source folder for this site' };
+    const full = path.posix.join(folder, rel);
+    const w = await _write_user_drive_file(uid, await get_account_default_project_id(uid), path.posix.dirname(full), path.posix.basename(full), Buffer.from(content, 'utf8'), _drive_content_type_for(path.posix.basename(full)));
+    if (w.code < 0) return w;
+    return { code: 1, data: { path: rel, size: w.data.size } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// ── Plan A: static-site SOURCE on the STUDIO drive (real filesystem, pinned to
+// the home region, never replicated) so codex can edit it in place — no temp
+// dir, no Spaces round-trip for editing. Keyed by the account project id (same
+// key the user drive used), under /static-sites/<site>:
+//   <studio_drive_path>/<account_project_id>/<site_folder>/...
+// Serving still snapshots to Spaces at deploy time; this is only the editable source.
+const _static_site_fs_dir = async (uid, site_folder) => {
+  const ref = await get_account_default_project_id(uid);
+  const folder = String(site_folder || '').replace(/^\/+|\/+$/g, '');
+  // Containment: the resolved dir must stay under this account's own root, so a
+  // crafted site_folder/draft_folder ('../../other-account', '../../../etc') can't
+  // escape the tenant or reach the host filesystem.
+  const base = path.join(_conf.studio_drive_path, ref);
+  const dir = path.resolve(base, folder);
+  if (dir !== base && !dir.startsWith(base + path.sep)) throw new Error('invalid site_folder path');
+  return { ref, dir };
+};
+
+// Bulk-write source files to the fs (create + upload). Each file is
+// { path, content (utf8) | content_b64 (binary) }.
+export const ingest_static_site_source = async (req) => {
+  try {
+    const { uid, site_folder, files } = req || {};
+    if (!uid || !site_folder || !Array.isArray(files)) return { code: -1, data: 'uid + site_folder + files[] required' };
+    const { dir } = await _static_site_fs_dir(uid, site_folder);
+    fs.mkdirSync(dir, { recursive: true });
+    let count = 0;
+    for (const f of files) {
+      const rel = String(f.path || '').replace(/^\/+/, '');
+      if (!rel) continue;
+      const full = path.resolve(dir, rel);
+      if (full !== dir && !full.startsWith(dir + path.sep)) continue; // reject path traversal in per-file paths
+      const parent = path.dirname(full);
+      fs.mkdirSync(parent, { recursive: true });
+      const buf = f.content_b64 != null ? Buffer.from(f.content_b64, 'base64') : Buffer.from(f.content ?? '', 'utf8');
+      const w = await fs_module.save_file(full, buf);
+      if (w.code < 0) return { code: -1, data: `write failed for ${rel}: ${w.data}` };
+      count++;
+    }
+    return { code: 1, data: { dir, file_count: count } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Read every file under the site's source dir (deploy → snapshot to Spaces).
+// Returns [{ path, content_b64, content_type }].
+export const read_static_site_source = async (req) => {
+  try {
+    const { uid, site_folder } = req || {};
+    if (!uid || !site_folder) return { code: -1, data: 'uid + site_folder required' };
+    const { dir } = await _static_site_fs_dir(uid, site_folder);
+    if (!(await file_exists(dir))) return { code: -1, data: `source dir not found: ${dir}` };
+    const scan = await fs_module.dree_scan(dir, { stat: true, size: true, depth: 100, symbolicLinks: false, hash: false });
+    if (scan.code < 0) return { code: -1, data: scan.data };
+    const files = [];
+    const walk = async (node) => {
+      if (!node) return;
+      if (node.type === 'file') {
+        const rd = await fs_module.read_file(node.path, { encoding: null, flag: 'r' });
+        if (rd.code === 1) {
+          const buf = Buffer.isBuffer(rd.data) ? rd.data : Buffer.from(rd.data);
+          const rel = node.path.replace(dir, '').replace(/^\/+/, '');
+          files.push({ path: rel, content_b64: buf.toString('base64'), content_type: _drive_content_type_for(node.name || rel) });
+        }
+      }
+      for (const c of node.children || []) await walk(c);
+    };
+    await walk(scan.data);
+    return { code: 1, data: { dir, file_count: files.length, files } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Single source of truth for a static site's source dir on the studio fs, so
+// the vibe flow (codex cwd), deploy (read), and restore all resolve the SAME
+// path. ai_module calls this so it never has to recompute the account ref.
+export const get_static_site_dir = async (req) => {
+  try {
+    const { uid, site_folder } = req || {};
+    if (!uid || !site_folder) return { code: -1, data: 'uid + site_folder required' };
+    const { ref, dir } = await _static_site_fs_dir(uid, site_folder);
+    return { code: 1, data: { ref, dir } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// List the account's static-site source folders on the studio fs. The create
+// wizard's "choose an existing folder" picker uses this — a user's sites/uploads
+// live here (studio fs), NOT on the Spaces user drive (which is why the old
+// get_drive_files_user picker showed nothing). Account-scoped (no app yet).
+export const list_static_site_folders = async (req) => {
+  try {
+    const uid = req?.uid || req?.token_ret?.data?.uid;
+    if (!uid) return { code: -1, data: 'not authorized' };
+    const ref = await get_account_default_project_id(uid);
+    const base = path.join(_conf.studio_drive_path, ref, 'static-sites');
+    if (!fs.existsSync(base)) return { code: 1, data: { folders: [] } };
+    const folders = [];
+    for (const e of fs.readdirSync(base, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const dir = path.join(base, e.name);
+      let bytes = 0;
+      let file_count = 0;
+      let has_index = false;
+      let mtime = 0;
+      let birthtime = 0;
+      try {
+        const walk = (d, rel) => {
+          for (const f of fs.readdirSync(d, { withFileTypes: true })) {
+            const r = rel ? rel + '/' + f.name : f.name;
+            const p = path.join(d, f.name);
+            if (f.isDirectory()) walk(p, r);
+            else {
+              file_count++;
+              try {
+                bytes += fs.statSync(p).size;
+              } catch (err) {}
+              if (/^index\.html?$/i.test(r)) has_index = true;
+            }
+          }
+        };
+        walk(dir, '');
+        const st = fs.statSync(dir);
+        mtime = st.mtimeMs;
+        // Creation time (ext4 stores crtime as birthtime); fall back where the
+        // filesystem doesn't report it so the field is always populated.
+        birthtime = st.birthtimeMs || st.ctimeMs || st.mtimeMs;
+      } catch (err) {}
+      folders.push({ folder_path: `/static-sites/${e.name}`, file_path: '/static-sites', folder_name: e.name, file_count, bytes, has_index, mtime, birthtime });
+    }
+    folders.sort((a, b) => b.mtime - a.mtime);
+    return { code: 1, data: { folders } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Reap abandoned static-site draft folders: any /static-sites/* dir not adopted
+// by a live static_website app AND older than max_age_hours. Fail-safe — if the
+// app enumeration fails we abort and delete NOTHING (never risk a live source).
+// dry_run (default true) reports without deleting. Called by the daily cron.
+export const cleanup_static_site_drafts = async (req) => {
+  try {
+    const dry_run = !(req && req.dry_run === false); // default true; pass dry_run:false to actually delete
+    const max_age_hours = (req && req.max_age_hours) || 24;
+    const max_age_ms = max_age_hours * 3600000;
+
+    // 1) Referenced set from LIVE apps. Any failure -> abort, delete nothing.
+    let apps;
+    try {
+      const r = await db_module.find_couch_query('xuda_master', { selector: { app_type: 'static_website' }, limit: 100000 });
+      apps = (r && r.docs) || [];
+    } catch (e) {
+      return { code: -1, data: 'aborted: could not enumerate apps (' + e.message + ')' };
+    }
+    if (!Array.isArray(apps)) return { code: -1, data: 'aborted: app enumeration returned no array' };
+    const referenced = new Set();
+    for (const a of apps) {
+      const fp = a && a.static_website && a.static_website.source && a.static_website.source.folder_path;
+      if (typeof fp === 'string' && fp.indexOf('/static-sites/') === 0)
+        referenced.add(
+          fp
+            .replace(/^\/+|\/+$/g, '')
+            .split('/')
+            .pop(),
+        );
+    }
+
+    // 2) Walk the studio fs, classify each /static-sites/* folder. Match by name
+    // (random-suffixed, globally unique in practice) — a false match only keeps
+    // an orphan, it never deletes a live source.
+    const now = Date.now();
+    const base_root = _conf.studio_drive_path;
+    const report = { scanned: 0, kept_referenced: 0, kept_recent: 0, deleted: [], errors: [], dry_run, max_age_hours, referenced_count: referenced.size };
+    let refs = [];
+    try {
+      refs = fs.readdirSync(base_root);
+    } catch (e) {
+      return { code: -1, data: 'aborted: cannot read studio_drive_path (' + e.message + ')' };
+    }
+    for (const ref of refs) {
+      const ss = path.join(base_root, ref, 'static-sites');
+      let names = [];
+      try {
+        if (!fs.existsSync(ss)) continue;
+        names = fs.readdirSync(ss);
+      } catch (e) {
+        continue;
+      }
+      for (const name of names) {
+        const dir = path.join(ss, name);
+        let st;
+        try {
+          st = fs.statSync(dir);
+          if (!st.isDirectory()) continue;
+        } catch (e) {
+          continue;
+        }
+        report.scanned++;
+        if (referenced.has(name)) {
+          report.kept_referenced++;
+          continue;
+        }
+        const age_ms = now - st.mtimeMs;
+        if (age_ms <= max_age_ms) {
+          report.kept_recent++;
+          continue;
+        }
+        const entry = { ref: ref.slice(0, 16), name, age_h: +(age_ms / 3600000).toFixed(1) };
+        if (dry_run) {
+          report.deleted.push({ ...entry, would_delete: true });
+        } else {
+          try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            report.deleted.push(entry);
+          } catch (e) {
+            report.errors.push({ name, error: e.message });
+          }
+        }
+      }
+    }
+    return { code: 1, data: report };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Live DEV preview URL — serves the editable fs source (the uncommitted edits)
+// over the existing /studio-drive/ route (cross-region proxied), so the vibe
+// panel shows the dev files, not the deployed version. Relative assets resolve
+// at the sub-path; cache-bust with a ts query so the iframe always reloads fresh.
+export const get_static_site_preview_url = async (req) => {
+  try {
+    const { uid, site_folder } = req || {};
+    if (!uid || !site_folder) return { code: -1, data: 'uid + site_folder required' };
+    const { ref } = await _static_site_fs_dir(uid, site_folder);
+    const folder = String(site_folder).replace(/^\/+|\/+$/g, '');
+    return { code: 1, data: { url: `https://${process.env.XUDA_HOSTNAME}/studio-drive/${ref}/${folder}/index.html` } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Restore: overwrite the editable source on the studio fs with a deployed
+// version's snapshot (read from Spaces via its manifest). True replace — the dev
+// folder becomes exactly that version, so the next vibe/build starts clean.
+export const restore_site_fs_from_manifest = async (req) => {
+  try {
+    const { uid, site_folder, manifest } = req || {};
+    if (!uid || !site_folder || !manifest || typeof manifest !== 'object') return { code: -1, data: 'uid + site_folder + manifest required' };
+    const { dir } = await _static_site_fs_dir(uid, site_folder);
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+    fs.mkdirSync(dir, { recursive: true });
+    let count = 0;
+    for (const [p, entry] of Object.entries(manifest)) {
+      const rel = String(p || '').replace(/^\/+/, '');
+      if (!rel || !entry) continue;
+      const region = entry.region;
+      const Bucket = entry.bucket || entry.Bucket;
+      const Key = entry.key || entry.Key;
+      const s3 = region ? _drive_s3_for(region) : null;
+      if (!s3 || !Bucket || !Key) continue;
+      const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
+      const buf = await _stream_to_buffer(obj.Body);
+      const full = path.join(dir, rel);
+      fs.mkdirSync(path.dirname(full), { recursive: true });
+      fs.writeFileSync(full, buf);
+      count++;
+    }
+    return { code: 1, data: { dir, file_count: count } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+export const save_user_drive_file = async function (uid, drive_doc) {
+  const app_id = await get_account_default_project_id(uid);
+  const save_ret = await db_module.save_app_couch_doc(app_id, drive_doc);
+  return save_ret;
+};
+
+export const find_contact_query = async function (uid, opt) {
+  const app_id = await get_account_default_project_id(uid);
+  const ret = await db_module.find_app_couch_query(app_id, opt);
+  return ret;
+};
+
+function getExtensionFromString(str) {
+  // Extract extension using regex
+  const match = str.match(/\.([a-zA-Z0-9]+)(?:[?#].*)?$/);
+  return match ? match[1].toLowerCase() : '';
+}
+
+// ============================================================================
+//   Static-website source read (user drive -> deploy-ready blobs)
+// ============================================================================
+//
+// read_user_drive_folder is the bridge between a user's drive and the
+// static-site hosting layer (domains_module.deploy_site). Given a folder
+// reference in the user's drive, it walks every file at or below that
+// folder, pulls the bytes from Spaces/R2, and returns them shaped exactly
+// the way deploy_site wants: [{ path, content_b64, content_type }] where
+// `path` is RELATIVE to the folder reference (leading slash).
+//   reference "/my-site", file at file_path "/my-site/css" name "app.css"
+//   -> { path: "/css/app.css", ... }
+//   reference "/my-site", file at file_path "/my-site" name "index.html"
+//   -> { path: "/index.html", ... }
+
+const _drive_content_type_for = (name) => {
+  const ext = (getExtensionFromString(name) || '').toLowerCase();
+  const map = {
+    html: 'text/html',
+    htm: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    mjs: 'application/javascript',
+    json: 'application/json',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    ico: 'image/x-icon',
+    avif: 'image/avif',
+    txt: 'text/plain',
+    xml: 'application/xml',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+    eot: 'application/vnd.ms-fontobject',
+    map: 'application/json',
+    webmanifest: 'application/manifest+json',
+    pdf: 'application/pdf',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    wasm: 'application/wasm',
+  };
+  return map[ext] || 'application/octet-stream';
+};
+
+// Plan C / regional drives: a user's file lives in a specific region's
+// Spaces bucket (doc.bucket is keyed by region-host, e.g. "eu.xuda.ai").
+// Because this read can run on a different server than where the file
+// lives (create_static_website runs on master; the file may be in eu),
+// we must address the file's OWN region — not the current server's.
+// Spaces is S3 over the internet, so any server can reach any region.
+const _drive_s3_cache = {};
+const _drive_s3_for = (region_host) => {
+  const conf = _conf.storage_bucket?.[region_host];
+  if (!conf) return null;
+  if (!_drive_s3_cache[region_host]) {
+    _drive_s3_cache[region_host] = new S3Client({
+      endpoint: conf.endpoint,
+      region: conf.region,
+      credentials: _storage_credentials(),
+      forcePathStyle: _is_r2(),
+    });
+  }
+  return _drive_s3_cache[region_host];
+};
+
+// Pick which region to read a file from: prefer the current server's
+// region if the file is replicated there (lowest latency), else any
+// region in the file's bucket map that we have config for.
+const _pick_file_region = (doc) => {
+  const bmap = doc?.bucket || {};
+  const here = process.env.XUDA_HOSTNAME;
+  if (bmap[here] && _conf.storage_bucket?.[here]) return here;
+  for (const region of Object.keys(bmap)) {
+    if (_conf.storage_bucket?.[region]) return region;
+  }
+  return null;
+};
+
+const _stream_to_buffer = async (stream) => {
+  if (!stream) return Buffer.alloc(0);
+  // AWS SDK v3 Body is a Node Readable in this runtime.
+  if (typeof stream.transformToByteArray === 'function') {
+    return Buffer.from(await stream.transformToByteArray());
+  }
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks);
+};
+
+export const read_user_drive_folder = async (req) => {
+  try {
+    const { uid } = req || {};
+    if (!uid) return { code: -1, data: 'uid required' };
+    // Normalize the folder reference: strip trailing slashes; '' -> '/'.
+    const root = String(req.folder_path || '/').replace(/\/+$/, '') || '/';
+
+    const app_id = await get_account_default_project_id(uid);
+    const ret = await db_module.find_app_couch_query(app_id, {
+      selector: { docType: 'user_drive', type: 'file', stat: 3 },
+      limit: 100000,
+    });
+
+    // Keep only files at the reference folder or any subfolder of it.
+    const docs = (ret?.docs || []).filter((d) => {
+      const fp = d.file_path || '/';
+      if (root === '/') return true;
+      return fp === root || fp.startsWith(root + '/');
+    });
+    if (!docs.length) return { code: -1, data: `no files found under ${root}` };
+
+    const files = [];
+    const skipped = [];
+    for (const d of docs) {
+      // Resolve the file's own region, then read from THAT region's bucket.
+      const region = _pick_file_region(d);
+      const b = (region && d.bucket?.[region]) || {};
+      const Bucket = b.Bucket || b.bucket || (region && _conf.storage_bucket?.[region]?.name);
+      const Key = b.Key || b.key;
+      const s3 = region ? _drive_s3_for(region) : null;
+      if (!s3 || !Bucket || !Key) {
+        // No reachable region (e.g. datacenter-scp file with no Spaces
+        // entry, or a region we have no config for) — surface it.
+        skipped.push(d.originalname || d._id);
+        continue;
+      }
+      try {
+        const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
+        const buf = await _stream_to_buffer(obj.Body);
+        const fp = d.file_path || '/';
+        const rel_dir = root === '/' ? fp : fp.slice(root.length); // '' | '/css'
+        const rel_path = path.posix.join('/', rel_dir || '/', d.originalname);
+        files.push({
+          path: rel_path,
+          content_b64: buf.toString('base64'),
+          content_type: d.mime || _drive_content_type_for(d.originalname),
+        });
+      } catch (err) {
+        console.error('[read_user_drive_folder] read fail', d._id, err.message);
+        skipped.push(d.originalname || d._id);
+      }
+    }
+
+    if (!files.length) return { code: -1, data: `no readable files under ${root}` };
+    return { code: 1, data: { files, file_count: files.length, skipped } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// put_site_files — snapshot a set of static-site files into ONE region's
+// Spaces bucket under sites/{site_id}/{version}/{path}, public-read. Each
+// deploy writes a fresh immutable version directory, so older versions stay
+// intact for rollback. The router serves a site by fetching the returned
+// `location` (a public DO Spaces URL, globally reachable — Cloudflare caches
+// it at the edge), so no per-request cross-region copy is needed.
+//
+// Files land in the app's home region (data residency / Plan C). The returned
+// manifest is what the site doc stores as the version snapshot.
+//
+// req: { region_host, site_id, version, files:[{ path, content_b64, content_type? }] }
+// -> { manifest:{ [path]:{ key, bucket, region, location, content_type, bytes } }, file_count, bytes, region, version }
+export const put_site_files = async (req) => {
+  try {
+    const { site_id, version } = req || {};
+    const files = Array.isArray(req?.files) ? req.files : [];
+    if (!site_id || !version) return { code: -1, data: 'site_id and version required' };
+    if (!files.length) return { code: -1, data: 'no files' };
+
+    // Resolve the target region: caller's region_host if we have config for it,
+    // else fall back to this server's own region.
+    const region_host = req.region_host && _conf.storage_bucket?.[req.region_host] ? req.region_host : process.env.XUDA_HOSTNAME;
+    const conf = _conf.storage_bucket?.[region_host];
+    if (!conf) return { code: -1, data: `no storage config for region ${region_host}` };
+    const s3 = _drive_s3_for(region_host);
+    const Bucket = conf.name;
+    if (!s3 || !Bucket) return { code: -1, data: `no S3 client for region ${region_host}` };
+
+    const manifest = {};
+    let bytes = 0;
+    for (const f of files) {
+      const raw = String(f.path || '').replace(/\\/g, '/');
+      const norm = path.posix.join('/', raw); // '/index.html', '/css/app.css'
+      if (!norm || norm === '/' || norm.includes('..')) {
+        if (norm.includes('..')) return { code: -1, data: `bad path: ${raw}` };
+        continue;
+      }
+      const body = Buffer.from(String(f.content_b64 || ''), 'base64');
+      const content_type = f.content_type || _drive_content_type_for(norm) || 'application/octet-stream';
+      const Key = `sites/${site_id}/${version}${norm}`;
+      const up = new Upload({
+        client: s3,
+        params: { Bucket, Key, Body: body, ContentType: content_type },
+      });
+      await up.done();
+      // Canonical public URL, rebuilt from the Key (custom domain on R2).
+      const location = _public_url_for(region_host, Key);
+      manifest[norm] = { key: Key, bucket: Bucket, region: region_host, location, content_type, bytes: body.length };
+      bytes += body.length;
+    }
+
+    if (!Object.keys(manifest).length) return { code: -1, data: 'no valid files to upload' };
+    return { code: 1, data: { manifest, file_count: Object.keys(manifest).length, bytes, region: region_host, version } };
+  } catch (err) {
+    console.error('[put_site_files]', err);
+    return { code: -400, data: err.message };
+  }
+};
+
+// delete_site_files — best-effort removal of a site's (or one version's)
+// objects from its region bucket. Used by domains.delete_site so deleting a
+// site reclaims storage instead of orphaning blobs.
+// req: { region_host, site_id, version? }
+export const delete_site_files = async (req) => {
+  try {
+    const { site_id } = req || {};
+    if (!site_id) return { code: -1, data: 'site_id required' };
+    const region_host = req.region_host && _conf.storage_bucket?.[req.region_host] ? req.region_host : process.env.XUDA_HOSTNAME;
+    const conf = _conf.storage_bucket?.[region_host];
+    if (!conf) return { code: 1, data: { deleted: 0 } };
+    const s3 = _drive_s3_for(region_host);
+    const Bucket = conf.name;
+    const prefix = req.version ? `sites/${site_id}/${req.version}/` : `sites/${site_id}/`;
+
+    let deleted = 0;
+    let ContinuationToken;
+    const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
+    do {
+      const list = await s3.send(new ListObjectsV2Command({ Bucket, Prefix: prefix, ContinuationToken }));
+      for (const obj of list.Contents || []) {
+        await s3.send(new DeleteObjectCommand({ Bucket, Key: obj.Key }));
+        deleted++;
+      }
+      ContinuationToken = list.IsTruncated ? list.NextContinuationToken : undefined;
+    } while (ContinuationToken);
+
+    return { code: 1, data: { deleted, region: region_host } };
+  } catch (err) {
+    console.error('[delete_site_files]', err);
+    return { code: -400, data: err.message };
+  }
+};
+
+// Explicitly exporting dynamic functions for ESM compatibility
+export const get_drive_files_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await get_drive_files(req, job_id, headers, file_obj);
+};
+export const get_drive_files_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await get_drive_files(req, job_id, headers, file_obj);
+});
+export const get_drive_files_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await get_drive_files(req, job_id, headers, file_obj);
+};
+
+export const get_drive_file_info_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await get_drive_file_info(req, job_id, headers, file_obj);
+};
+export const get_drive_file_info_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await get_drive_file_info(req, job_id, headers, file_obj);
+});
+export const get_drive_file_info_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await get_drive_file_info(req, job_id, headers, file_obj);
+};
+
+export const delete_drive_files_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await delete_drive_files(req, job_id, headers, file_obj);
+};
+export const delete_drive_files_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await delete_drive_files(req, job_id, headers, file_obj);
+});
+export const delete_drive_files_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await delete_drive_files(req, job_id, headers, file_obj);
+};
+
+export const extract_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await extract_drive_file(req, job_id, headers, file_obj);
+};
+export const extract_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await extract_drive_file(req, job_id, headers, file_obj);
+});
+export const extract_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await extract_drive_file(req, job_id, headers, file_obj);
+};
+
+export const upload_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await upload_drive_file(req, job_id, headers, file_obj);
+};
+export const upload_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await upload_drive_file(req, job_id, headers, file_obj);
+});
+export const upload_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await upload_drive_file(req, job_id, headers, file_obj);
+};
+
+export const update_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await update_drive_file(req, job_id, headers, file_obj);
+};
+export const update_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await update_drive_file(req, job_id, headers, file_obj);
+});
+export const update_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await update_drive_file(req, job_id, headers, file_obj);
+};
+
+export const create_drive_folder_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await create_drive_folder(req, job_id, headers, file_obj);
+};
+export const create_drive_folder_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await create_drive_folder(req, job_id, headers, file_obj);
+});
+export const create_drive_folder_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await create_drive_folder(req, job_id, headers, file_obj);
+};
+
+export const rename_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await rename_drive_file(req, job_id, headers, file_obj);
+};
+export const rename_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await rename_drive_file(req, job_id, headers, file_obj);
+});
+export const rename_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await rename_drive_file(req, job_id, headers, file_obj);
+};
+
+export const rename_drive_folder_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await rename_drive_folder(req, job_id, headers, file_obj);
+};
+export const rename_drive_folder_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await rename_drive_folder(req, job_id, headers, file_obj);
+});
+export const rename_drive_folder_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await rename_drive_folder(req, job_id, headers, file_obj);
+};
+
+export const update_drive_file_sharing_mode_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await update_drive_file_sharing_mode(req, job_id, headers, file_obj);
+};
+export const update_drive_file_sharing_mode_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await update_drive_file_sharing_mode(req, job_id, headers, file_obj);
+});
+export const update_drive_file_sharing_mode_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await update_drive_file_sharing_mode(req, job_id, headers, file_obj);
+};
+
+export const star_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await star_drive_file(req, job_id, headers, file_obj);
+};
+export const star_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await star_drive_file(req, job_id, headers, file_obj);
+});
+export const star_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await star_drive_file(req, job_id, headers, file_obj);
+};
+
+export const delete_file_bulk_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await delete_file_bulk(req, job_id, headers, file_obj);
+};
+export const delete_file_bulk_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await delete_file_bulk(req, job_id, headers, file_obj);
+});
+export const delete_file_bulk_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await delete_file_bulk(req, job_id, headers, file_obj);
+};
+
+export const check_drive_file_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await check_drive_file(req, job_id, headers, file_obj);
+};
+export const check_drive_files_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await check_drive_files(req, job_id, headers, file_obj);
+};
+export const check_drive_file_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await check_drive_file(req, job_id, headers, file_obj);
+});
+export const check_drive_files_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await check_drive_files(req, job_id, headers, file_obj);
+});
+export const check_drive_file_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await check_drive_file(req, job_id, headers, file_obj);
+};
+export const check_drive_files_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await check_drive_files(req, job_id, headers, file_obj);
+};
+
+export const update_drive_file_tags_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await update_drive_file_tags(req, job_id, headers, file_obj);
+};
+export const update_drive_file_tags_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await update_drive_file_tags(req, job_id, headers, file_obj);
+});
+export const update_drive_file_tags_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await update_drive_file_tags(req, job_id, headers, file_obj);
+};
+
+export const update_drive_addons_workspace = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'workspace';
+  return await update_drive_addons(req, job_id, headers, file_obj);
+};
+export const update_drive_addons_studio = _common.location_sensitive(async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'studio';
+  return await update_drive_addons(req, job_id, headers, file_obj);
+});
+export const update_drive_addons_user = async (req, job_id, headers, file_obj) => {
+  req.drive_type = 'user';
+  if (!req.uid && req.token_ret?.data?.uid) req.uid = req.token_ret.data.uid; // user-drive ops resolve the project from the authenticated uid
+  return await update_drive_addons(req, job_id, headers, file_obj);
+};
+
+export const file_upload_validator = function (file_name) {
+  // 1. Safety check: ensure file_name exists
+  if (!file_name || typeof file_name !== 'string') {
+    return { valid: false, error: 'Invalid filename' };
+  }
+
+  // 2. Extract the extension (remove dot and make lowercase)
+  const ext = file_name.split('.').pop().toLowerCase();
+
+  // 3. Validate using Switch
+  switch (ext) {
+    // ==============================
+    // VALIDATE AUDIO FILES
+    // ==============================
+    case 'mp3':
+      return { valid: true, category: 'audio', mime: 'audio/mpeg' };
+    case 'wav':
+      return { valid: true, category: 'audio', mime: 'audio/wav' };
+    case 'ogg':
+      return { valid: true, category: 'audio', mime: 'audio/ogg' };
+    case 'm4a':
+      return { valid: true, category: 'audio', mime: 'audio/mp4' };
+
+    // ==============================
+    // VALIDATE VIDEO FILES
+    // ==============================
+    case 'mp4':
+      return { valid: true, category: 'video', mime: 'video/mp4' };
+    case 'webm':
+      return { valid: true, category: 'video', mime: 'video/webm' };
+    case 'avi':
+      return { valid: true, category: 'video', mime: 'video/x-msvideo' };
+    case 'mov':
+      return { valid: true, category: 'video', mime: 'video/quicktime' };
+
+    // ==============================
+    // VALIDATE PICTURE FILES
+    // ==============================
+    case 'jpg':
+    case 'jpeg':
+      return { valid: true, category: 'image', mime: 'image/jpeg' };
+    case 'png':
+      return { valid: true, category: 'image', mime: 'image/png' };
+    case 'gif':
+      return { valid: true, category: 'image', mime: 'image/gif' };
+    case 'svg':
+      return { valid: true, category: 'image', mime: 'image/svg+xml' };
+    case 'webp':
+      return { valid: true, category: 'image', mime: 'image/webp' };
+
+    // ==============================
+    // VALIDATE TEXT / CODE FILES
+    // ==============================
+    case 'c':
+      return { valid: true, category: 'text', mime: 'text/x-c' };
+    case 'cpp':
+      return { valid: true, category: 'text', mime: 'text/x-c++' };
+    case 'cs':
+      return { valid: true, category: 'text', mime: 'text/x-csharp' };
+    case 'css':
+      return { valid: true, category: 'text', mime: 'text/css' };
+    case 'doc':
+      return { valid: true, category: 'document', mime: 'application/msword' };
+    case 'docx':
+      return { valid: true, category: 'document', mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' };
+    case 'go':
+      return { valid: true, category: 'text', mime: 'text/x-golang' };
+    case 'html':
+      return { valid: true, category: 'text', mime: 'text/html' };
+    case 'java':
+      return { valid: true, category: 'text', mime: 'text/x-java' };
+    case 'js':
+      return { valid: true, category: 'text', mime: 'text/javascript' };
+    case 'json':
+      return { valid: true, category: 'text', mime: 'application/json' };
+    case 'md':
+      return { valid: true, category: 'text', mime: 'text/markdown' };
+    case 'pdf':
+      return { valid: true, category: 'document', mime: 'application/pdf' };
+    case 'php':
+      return { valid: true, category: 'text', mime: 'text/x-php' };
+    case 'pptx':
+      return { valid: true, category: 'document', mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' };
+    case 'py':
+      return { valid: true, category: 'text', mime: 'text/x-python' }; // or text/x-script.python
+    case 'rb':
+      return { valid: true, category: 'text', mime: 'text/x-ruby' };
+    case 'sh':
+      return { valid: true, category: 'text', mime: 'application/x-sh' };
+    case 'tex':
+      return { valid: true, category: 'text', mime: 'text/x-tex' };
+    case 'ts':
+      return { valid: true, category: 'text', mime: 'application/typescript' };
+    case 'txt':
+      return { valid: true, category: 'text', mime: 'text/plain' };
+
+    // ==============================
+    // VALIDATE TEXT / CODE FILES
+    // ==============================
+    case 'csv':
+      return { valid: true, category: 'text', mime: 'text/csv' };
+    case 'json':
+      return { valid: true, category: 'text', mime: 'application/json' };
+    case 'csv':
+      return { valid: true, category: 'text', mime: 'text/csv' };
+    case 'xls':
+      return { valid: true, category: 'document', mime: 'application/vnd.ms-excel' };
+    case 'xlsx':
+      return { valid: true, category: 'document', mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' };
+    case 'md':
+      return { valid: true, category: 'text', mime: 'text/markdown' };
+
+    // ==============================
+    // VALIDATE ARCHIVE & PACKAGE FILES
+    // ==============================
+    case 'zip':
+      return { valid: true, category: 'archive', mime: 'application/zip' };
+    case 'rar':
+      return { valid: true, category: 'archive', mime: 'application/vnd.rar' };
+    case '7z':
+      return { valid: true, category: 'archive', mime: 'application/x-7z-compressed' };
+    case 'tar':
+      return { valid: true, category: 'archive', mime: 'application/x-tar' };
+    case 'gz':
+    case 'tgz':
+      return { valid: true, category: 'archive', mime: 'application/gzip' };
+    case 'bz2':
+      return { valid: true, category: 'archive', mime: 'application/x-bzip2' };
+    case 'xz':
+      return { valid: true, category: 'archive', mime: 'application/x-xz' };
+    case 'z':
+      return { valid: true, category: 'archive', mime: 'application/x-compress' };
+    case 'lzma':
+      return { valid: true, category: 'archive', mime: 'application/x-lzma' };
+    case 'cpio':
+      return { valid: true, category: 'archive', mime: 'application/x-cpio' };
+    case 'lzh':
+    case 'lha':
+      return { valid: true, category: 'archive', mime: 'application/x-lzh' };
+    case 'ar':
+      return { valid: true, category: 'archive', mime: 'application/x-archive' };
+
+    // Linux / Java Packages
+    case 'deb':
+      return { valid: true, category: 'archive', mime: 'application/vnd.debian.binary-package' };
+    case 'rpm':
+      return { valid: true, category: 'archive', mime: 'application/x-rpm' };
+    case 'jar':
+      return { valid: true, category: 'archive', mime: 'application/java-archive' };
+    case 'war':
+      return { valid: true, category: 'archive', mime: 'application/x-webarchive' };
+    case 'ear':
+      return { valid: true, category: 'archive', mime: 'application/octet-stream' };
+    case 'apk':
+      return { valid: true, category: 'archive', mime: 'application/vnd.android.package-archive' };
+    case 'ipa':
+      return { valid: true, category: 'archive', mime: 'application/x-itunes-ipa' };
+
+    // ==============================
+    // PICTURES & DESIGN
+    // ==============================
+    case 'tiff':
+    case 'tif':
+      return { valid: true, category: 'image', mime: 'image/tiff' };
+    case 'psd':
+      return { valid: true, category: 'design', mime: 'image/vnd.adobe.photoshop' };
+    case 'ai':
+      return { valid: true, category: 'design', mime: 'application/illustrator' };
+    case 'eps':
+      return { valid: true, category: 'design', mime: 'application/eps' };
+
+    // ==============================
+    // DOCUMENTS & SPREADSHEETS
+    // ==============================
+    case 'xls':
+      return { valid: true, category: 'document', mime: 'application/vnd.ms-excel' };
+    case 'xlsx':
+    case 'xslx': // Handling common typo
+      return { valid: true, category: 'document', mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' };
+
+    // ==============================
+    // FONTS
+    // ==============================
+    case 'ttf':
+      return { valid: true, category: 'font', mime: 'font/ttf' };
+    case 'otf':
+      return { valid: true, category: 'font', mime: 'font/otf' };
+    case 'woff':
+      return { valid: true, category: 'font', mime: 'font/woff' };
+    case 'woff2':
+      return { valid: true, category: 'font', mime: 'font/woff2' };
+
+    // ==============================
+    // SYSTEM & CONFIG
+    // ==============================
+    case 'plist':
+      return { valid: true, category: 'text', mime: 'application/x-plist' };
+
+    // ==============================
+    // DEFAULT (INVALID)
+    // ==============================
+    default:
+      return { valid: false, error: `Unsupported file extension: .${ext}` };
+  }
+};