@xuda.io/drive_module 1.1.1499 → 1.1.1501

package/index.mjs

@@ -5,6 +5,7 @@ import fse from 'fs-extra';
 import unzipper from 'unzipper';
 import fs from 'fs';
 import os from 'os';
+import child_process from 'child_process';
 import tesseract from 'node-tesseract-ocr';
 import countryLanguage from 'country-language';
 import url from 'url';
@@ -29,6 +30,10 @@ const { get_account_default_project_id } = await import(path.join(process.env.XU
 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`);
+// UI-113: the Drive storage ladder is one line item on the consolidated
+// subscription, so drive_set_plan drives Stripe the same way every other module
+// tier does (add_subscription_item to buy or reprice, remove on the free tier).
+const stripe_ms = await import(`${module_path}/stripe_module/index_ms.mjs`);
 
 // const account_msa = await import(`${module_path}/account_module/index_msa.mjs`);
 
@@ -222,13 +227,15 @@ export const get_drive_files = async (req) => {
           }
           try {
             files.sizeInBytes += doc.size;
+            const access_link = `https://${domain}/${drive_type}-drive/${datasource_id || app_id_reference || uid}/${doc._id}${ts}`;
             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}`,
+              access_link,
+              ...preview_links_for(doc, access_link),
               is_archive: doc.is_archive,
               public: doc.public,
               path: doc.file_path,
@@ -672,6 +679,9 @@ export const update_drive_file = async (req, job_id, headers, file_obj) => {
 
     doc = { ...doc, ...(await get_file_info(tempPath)) };
 
+    // New bytes, so any preview on the doc now shows the old content. Re-queue it.
+    if (is_office_preview_ext(doc.file_ext)) doc.preview_stat = 1;
+
     let save_ret;
     let ref;
     switch (drive_type) {
@@ -722,6 +732,10 @@ export const update_drive_file = async (req, job_id, headers, file_obj) => {
 
     let file_url = get_file_url(drive_type, file_name, ref);
 
+    if (doc.preview_stat === 1) {
+      generate_drive_file_preview({ app_id, drive_type, uid, doc_id: doc._id }).catch(() => {});
+    }
+
     return {
       code: 760,
       data: {
@@ -1888,6 +1902,9 @@ export const upload_drive_file = async (req, job_id, headers = {}, file_obj) =>
       drive_type,
       mime: file_obj.mimetype,
       ocr_stat: ['image', 'application', 'text'].includes(file_obj.mimetype.split('/')[0]) ? 1 : 0,
+      // studio drive keeps its files on local disk rather than in a bucket, and the
+      // preview reader fetches from the bucket, so it is not a candidate.
+      preview_stat: is_office_preview_ext(ext) && drive_type !== 'studio' ? 1 : 0,
       target_file,
       file_path: file_path || '/',
       size: stat.isFile() ? stat.size : 0,
@@ -2016,6 +2033,13 @@ export const upload_drive_file = async (req, job_id, headers = {}, file_obj) =>
 
     await fs_module.unlink(tempPath);
 
+    // Office files get a rendered preview. Fire and forget: converting takes seconds and
+    // an upload must not wait for it, nor fail because of it. The doc already carries
+    // preview_stat 1, so if this box never gets to it the sweep will.
+    if (doc.preview_stat === 1) {
+      generate_drive_file_preview({ app_id: req.app_id, drive_type, uid, doc_id: doc._id }).catch(() => {});
+    }
+
     return {
       code: 760,
       data: {
@@ -2347,19 +2371,100 @@ export const check_drive_file = async (req, job_id, headers, file_obj) => {
   return ret.files[0];
 };
 
-const ocr_drive_file = async (app_id, doc) => {
-  const { drive_type, uid, file_path, originalname } = doc;
+// Which languages tesseract on THIS box actually has traineddata for. Asked once and
+// cached: it shells out, and the answer cannot change while the process lives.
+let _tesseract_langs_cache;
+const tesseract_langs = () => {
+  if (_tesseract_langs_cache) return _tesseract_langs_cache;
+  try {
+    const out = child_process.execFileSync('tesseract', ['--list-langs'], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] });
+    // First line is a "List of available languages (N):" header, which has spaces in it.
+    const langs = out.split('\n').map((s) => s.trim()).filter((s) => s && !s.includes(' '));
+    _tesseract_langs_cache = new Set(langs.length ? langs : ['eng']);
+  } catch (err) {
+    console.warn('[drive_module] tesseract --list-langs failed, assuming eng only:', err.message);
+    _tesseract_langs_cache = new Set(['eng']);
+  }
+  return _tesseract_langs_cache;
+};
+
+// Pick the OCR languages for a file, from the country its upload came from.
+//
+// Two traps, both of which used to fail the whole OCR run:
+//  - country-language's getCountry REQUIRES a callback and throws "cb is not a function"
+//    for a missing or unknown code. doc.country comes from the cf-ipcountry header, which
+//    is absent on EVERY server-side write (AI output, plugin saves, restores), so this
+//    threw for most files and marked them ocr_stat 4.
+//  - a language whose traineddata is not installed makes tesseract exit with "Error during
+//    processing", losing the English pass along with it. So only offer what is on the box.
+const detectLanguageByCountry = (cfCountry) => {
+  const have = tesseract_langs();
+  const langs = ['eng'];
+  try {
+    const code = String(cfCountry || '').trim().toUpperCase();
+    const countryData = code ? countryLanguage.getCountry(code) : null;
+    for (const language of countryData?.languages || []) {
+      const iso = language?.iso639_2;
+      if (iso && have.has(iso) && !langs.includes(iso)) langs.push(iso);
+    }
+  } catch (err) {
+    // Unknown or missing country: English only, which is the right default and is what
+    // the caller wanted all along.
+  }
+  // Each extra language costs real time on every page, and the tail of a country's list
+  // is rarely what the document is written in.
+  return langs.slice(0, 4).join('+');
+};
 
-  let target_file = get_file_url(drive_type, path.join(file_path, doc._id), app_id || uid);
+// Put a drive file's bytes on local disk and hand back the path. EVERY OCR reader below
+// wants a real file: tesseract streams one, mammoth and node-xlsx take a `path`, pdf2image
+// rasterises one. They were being handed a URL instead, and a wrong URL at that (built
+// with the uid where the route wants the project id, and with the folder baked into the
+// filename), so the fetch 404'd and tesseract failed with "Error during processing" while
+// the text branch quietly stored an ENOENT string as the document's OCR text.
+//
+// The bytes are already in the region bucket, so read them straight from there and skip
+// HTTP entirely. Only a drive with no bucket entry (a datacenter workspace drive, whose
+// files are scp'd to the hosting box) still needs the round trip, and that one now uses a
+// URL built the same way the drive listing builds it.
+const ocr_file_to_tmp = async (app_id, doc) => {
+  const write_tmp = async (buffer) => {
+    const tmp_path = path.join(os.tmpdir(), `xuda_ocr_${await _common.xuda_get_uuid('tmp')}${doc.file_ext || path.extname(doc.originalname || '') || ''}`);
+    await fs.promises.writeFile(tmp_path, buffer);
+    return tmp_path;
+  };
+
+  const region = _pick_file_region(doc);
+  const { Bucket, Key } = _drive_bucket_for(doc, region);
+  const s3 = region ? _drive_s3_for(region) : null;
 
-  function addQueryParam(urlString, key, value) {
-    const parsedUrl = new url.URL(urlString);
-    parsedUrl.searchParams.set(key, value);
-    return parsedUrl.toString();
+  if (s3 && Bucket && Key) {
+    const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
+    return await write_tmp(await _stream_to_buffer(obj.Body));
   }
 
-  target_file = addQueryParam(target_file, 'xuda_internal_request_code', _conf.xuda_internal_request_code);
+  const ref = doc.drive_type === 'user' ? await get_account_default_project_id(doc.uid) : await _common.get_project_app_id(app_id);
+  const target = new url.URL(get_file_url(doc.drive_type, doc._id, ref));
+  target.searchParams.set('xuda_internal_request_code', _conf.xuda_internal_request_code);
+
+  const res = await fetch(target.toString());
+  if (!res.ok) throw new Error(`file unavailable (${res.status})`);
+  return await write_tmp(Buffer.from(await res.arrayBuffer()));
+};
 
+// read_file answers { code, data } and puts the ERROR MESSAGE in data when it fails, so
+// reading it blindly stored strings like "ENOENT: no such file" as the document's own
+// searchable text. A failed read has no text in it, and saying so is the honest answer.
+const read_text_for_ocr = async (file_path) => {
+  const ret = await fs_module.read_file(file_path);
+  if (!ret || ret.code < 0) throw new Error(`could not read file for ocr: ${ret?.data || 'unknown error'}`);
+  return String(ret.data || '');
+};
+
+const ocr_drive_file = async (app_id, doc) => {
+  const { drive_type, uid, file_path, originalname } = doc;
+
+  let target_file;
   let save_ret;
   try {
     doc.ocr_stat = 2;
@@ -2368,24 +2473,19 @@ const ocr_drive_file = async (app_id, doc) => {
 
     doc = await get_drive_doc('file', drive_type, app_id, uid, path.join(file_path, originalname));
 
-    let ocr = '';
+    target_file = await ocr_file_to_tmp(app_id, doc);
 
-    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 ocr = '';
 
     let lang = detectLanguageByCountry(doc.country);
 
     const generalConfig = { oem: 1, psm: 3, lang };
 
-    switch (doc.mime.split('/')[0]) {
+    // A doc written before mime was recorded would throw on .split here and be marked
+    // failed for ever. Fall back to the extension, which every drive doc carries.
+    const mime = doc.mime || _drive_content_type_for(doc.originalname || '') || '';
+
+    switch (mime.split('/')[0]) {
       case 'image': {
         ocr = await tesseract.recognize(target_file, generalConfig);
 
@@ -2393,7 +2493,7 @@ const ocr_drive_file = async (app_id, doc) => {
       }
 
       case 'application': {
-        switch (doc.mime.split('/')[1]) {
+        switch (mime.split('/')[1]) {
           case 'pdf': {
             const images = await convertPDF(target_file);
             for await (const imageData of images) {
@@ -2407,7 +2507,10 @@ const ocr_drive_file = async (app_id, doc) => {
             break;
           }
 
+          // 'nd.ms-excel' was a typo for the real .xls mime, so no legacy spreadsheet
+          // ever reached this branch. Both spellings kept, the wrong one costs nothing.
           case 'nd.ms-excel':
+          case 'vnd.ms-excel':
           case 'vnd.openxmlformats-officedocument.spreadsheetml.sheet': {
             const sheets = xlsx.parse(target_file);
             sheets.forEach((sheet) => {
@@ -2425,7 +2528,7 @@ const ocr_drive_file = async (app_id, doc) => {
             break;
 
           default:
-            ocr = (await fs_module.read_file(target_file)).data;
+            ocr = await read_text_for_ocr(target_file);
             break;
         }
         break;
@@ -2450,12 +2553,286 @@ const ocr_drive_file = async (app_id, doc) => {
     doc.ocr_stat = 4;
     doc.ocr_error = err.message;
   } finally {
+    // The bytes were copied here only so a reader could open them.
+    if (target_file) await fs.promises.unlink(target_file).catch(() => {});
     doc.ocr_stat_ts = Date.now();
 
     save_ret = await save_drive_doc(drive_type, uid, app_id, doc, file_path);
   }
 };
 
+// ── Office previews ────────────────────────────────────────────────────────────
+// A deck, a document or a spreadsheet had no preview anywhere in the Drive: the
+// thumbnail was a grey category tile and the lightbox said "No preview available".
+// So render one. Each office file gets two derived assets stored beside it:
+//
+//   pdf - the whole file, which the lightbox already knows how to show in an iframe
+//   png - page/slide one, which every thumbnail in the app can draw as an image
+//
+// The conversion needs LibreOffice on the box. Where it is absent the file simply
+// keeps its category tile, exactly as before, and preview_stat records that so the
+// sweep does not retry a box that can never succeed.
+//
+// preview_stat: 0 not applicable / unsupported here, 1 queued, 2 running, 3 done, 4 failed.
+const PREVIEW_OFFICE_EXTS = ['.pptx', '.ppt', '.docx', '.doc', '.xlsx', '.xls', '.odp', '.odt', '.ods', '.rtf'];
+
+const is_office_preview_ext = (ext) => PREVIEW_OFFICE_EXTS.includes(String(ext || '').toLowerCase());
+
+// Resolved once per process. `null` means "looked and it is not here", which is a
+// real answer and must not be retried on every file.
+let _soffice_bin_cache;
+const soffice_bin = () => {
+  if (_soffice_bin_cache !== undefined) return _soffice_bin_cache;
+  _soffice_bin_cache = ['/usr/bin/soffice', '/usr/bin/libreoffice', '/usr/lib/libreoffice/program/soffice'].find((p) => {
+    try {
+      return fs.existsSync(p);
+    } catch (_) {
+      return false;
+    }
+  }) || null;
+  if (!_soffice_bin_cache) console.warn('[drive_module] office previews disabled: no LibreOffice on this box');
+  return _soffice_bin_cache;
+};
+
+const run_cmd = (bin, args, { timeout_ms = 120000, cwd } = {}) =>
+  new Promise((resolve, reject) => {
+    const child = child_process.execFile(bin, args, { timeout: timeout_ms, cwd, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(`${path.basename(bin)} failed: ${err.message} ${String(stderr || '').slice(0, 300)}`));
+      resolve({ stdout, stderr });
+    });
+    child.on('error', reject);
+  });
+
+// Convert one office file into { pdf, png }. Runs entirely in a private temp dir so
+// two conversions of the same filename cannot collide, and so a partial run leaves
+// nothing behind.
+const render_office_preview = async (buffer, originalname) => {
+  const bin = soffice_bin();
+  if (!bin) return null;
+
+  const work_dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'xuda_preview_'));
+  const src_path = path.join(work_dir, `src${path.extname(originalname) || '.bin'}`);
+
+  try {
+    await fs.promises.writeFile(src_path, buffer);
+
+    // -env:UserInstallation gives this run its own profile dir. Without it concurrent
+    // conversions share ~/.config/libreoffice and the second one exits doing nothing.
+    await run_cmd(bin, [
+      '--headless',
+      '--norestore',
+      '--nolockcheck',
+      `-env:UserInstallation=file://${path.join(work_dir, 'lo_profile')}`,
+      '--convert-to',
+      'pdf',
+      '--outdir',
+      work_dir,
+      src_path,
+    ]);
+
+    const pdf_path = path.join(work_dir, 'src.pdf');
+    if (!fs.existsSync(pdf_path)) throw new Error('conversion produced no pdf');
+    const pdf = await fs.promises.readFile(pdf_path);
+
+    // Page one only, capped on width so a poster-sized slide does not become a
+    // multi-megabyte thumbnail. -singlefile keeps the output name predictable.
+    await run_cmd('/usr/bin/pdftoppm', ['-png', '-f', '1', '-l', '1', '-singlefile', '-scale-to-x', '960', '-scale-to-y', '-1', pdf_path, path.join(work_dir, 'page1')]);
+
+    const png_path = path.join(work_dir, 'page1.png');
+    if (!fs.existsSync(png_path)) throw new Error('conversion produced no page image');
+    const png = await fs.promises.readFile(png_path);
+
+    return { pdf, png };
+  } finally {
+    await rimraf(work_dir).catch(() => {});
+  }
+};
+
+// Store one derived asset next to the file it came from, in the same bucket and region.
+const put_preview_asset = async (region, base_key, suffix, body, content_type) => {
+  const Bucket = _conf.storage_bucket?.[region]?.name;
+  const s3 = _drive_s3_for(region);
+  if (!s3 || !Bucket) throw new Error(`no storage bucket for region ${region}`);
+  const Key = `${base_key}.preview.${suffix}`;
+  await s3.send(new PutObjectCommand({ Bucket, Key, Body: body, ContentType: content_type }));
+  return { Bucket, Key, key: Key };
+};
+
+// Build (or rebuild) the preview assets for one drive doc and record them on it.
+// Shaped like ocr_drive_file: takes the doc, mutates preview state, saves it back.
+const preview_drive_file = async (app_id, doc) => {
+  const { drive_type, uid, file_path } = doc;
+
+  try {
+    if (!soffice_bin()) {
+      doc.preview_stat = 0;
+      doc.preview_error = 'no converter on this box';
+      doc.preview_stat_ts = Date.now();
+      return await save_drive_doc(drive_type, uid, app_id, doc, file_path);
+    }
+
+    doc.preview_stat = 2;
+    doc.preview_stat_ts = Date.now();
+    await save_drive_doc(drive_type, uid, app_id, doc, file_path);
+
+    const region = _pick_file_region(doc);
+    const { Bucket, Key } = _drive_bucket_for(doc, region);
+    const s3 = region ? _drive_s3_for(region) : null;
+    if (!s3 || !Bucket || !Key) throw new Error('file bytes unavailable');
+
+    const obj = await s3.send(new GetObjectCommand({ Bucket, Key }));
+    const buffer = await _stream_to_buffer(obj.Body);
+
+    const rendered = await render_office_preview(buffer, doc.originalname || 'file');
+    if (!rendered) throw new Error('no converter on this box');
+
+    const [pdf_ref, png_ref] = await Promise.all([
+      put_preview_asset(region, Key, 'pdf', rendered.pdf, 'application/pdf'),
+      put_preview_asset(region, Key, 'png', rendered.png, 'image/png'),
+    ]);
+
+    doc.preview = { ...(doc.preview || {}), [region]: { pdf: pdf_ref, png: png_ref } };
+    doc.preview_stat = 3;
+    doc.preview_error = '';
+  } catch (err) {
+    doc.preview_stat = 4;
+    doc.preview_error = err.message;
+    console.error('[drive_module] preview failed for', doc?._id, err.message);
+  } finally {
+    doc.preview_stat_ts = Date.now();
+    await save_drive_doc(drive_type, uid, app_id, doc, file_path).catch(() => {});
+  }
+};
+
+// Stat 2 means "a box is working on this right now", and the work is in-process. So a
+// pm2 restart mid-run (a deploy, a crash, an OOM) leaves the doc claimed by a process that
+// no longer exists, and nothing ever looks at stat 2 again: it is a dead end, not a state.
+// Anything that has been "running" for longer than the slowest plausible job is therefore
+// finished-by-death, and goes back in the queue. STALE_MS is generous on purpose, a big
+// deck with images is a slow convert and reclaiming a LIVE job would run it twice.
+const STRANDED_STAT_MS = 15 * 60 * 1000;
+
+const reclaim_stranded = async (app_id, docType, stat_field, ts_field) => {
+  try {
+    const ret = await db_module.find_app_couch_query(app_id, {
+      selector: { docType, type: 'file', [stat_field]: 2 },
+      limit: 50,
+    });
+    const stale = (ret?.docs || []).filter((d) => !d[ts_field] || Date.now() - d[ts_field] > STRANDED_STAT_MS);
+    for (const doc of stale) {
+      doc[stat_field] = 1;
+      await save_drive_doc(doc.drive_type, doc.uid, docType === 'user_drive' ? null : app_id, doc, doc.file_path).catch(() => {});
+      console.warn(`[drive_module] reclaimed stranded ${stat_field}=2 on ${doc._id}`);
+    }
+  } catch (err) {
+    console.error('[drive_module] reclaim_stranded failed', docType, stat_field, err.message);
+  }
+};
+
+// Same sweep shape as run_drive_pending_ocr, and the same region-ownership rule:
+// only the box that owns the app converts its files, so an active/standby pair does
+// not run the same conversion twice and race the write.
+export const run_drive_pending_previews = async () => {
+  try {
+    if (!soffice_bin()) return { code: 1, data: 'no converter on this box' };
+
+    const app_res = await db_module.find_couch_query('xuda_master', {
+      selector: {
+        docType: 'app',
+        app_status_code: { $eq: 3 },
+        $or: [{ app_type: 'master' }, { app_type: 'instance' }, { app_type: 'datacenter' }],
+      },
+      limit: 99999,
+    });
+
+    let done = 0;
+    for (let app of app_res.docs) {
+      if (!_common.is_app_owned_by_local_box(app)) continue;
+
+      for (const docType of ['user_drive', 'workspace_drive']) {
+        const owner = docType === 'user_drive' ? null : app._id;
+
+        await reclaim_stranded(app._id, docType, 'preview_stat', 'preview_stat_ts');
+
+        const queued = await db_module.find_app_couch_query(app._id, {
+          selector: { docType, preview_stat: 1, stat: 3 },
+          limit: 5,
+        });
+        for await (let doc of queued.docs) {
+          await preview_drive_file(owner, doc);
+          done++;
+        }
+        if (queued.docs?.length) continue;
+
+        // Backfill: every file that predates this feature has no preview_stat at all, so
+        // the queued pass above can never see it. Filtered in JS rather than with $in on
+        // file_ext, which no index can serve.
+        const legacy = await db_module.find_app_couch_query(app._id, {
+          selector: { docType, stat: 3, type: 'file', preview_stat: { $exists: false } },
+          limit: 60,
+        });
+        const legacy_docs = legacy.docs || [];
+
+        // Stamp the ones that will never have a preview, so the batch above returns
+        // different docs next tick. Without this a drive whose first 60 files are all
+        // images hands back the same 60 for ever and the backfill never advances.
+        for await (let doc of legacy_docs.filter((d) => !is_office_preview_ext(d.file_ext))) {
+          doc.preview_stat = 0;
+          await save_drive_doc(doc.drive_type, doc.uid, owner, doc, doc.file_path).catch(() => {});
+        }
+
+        for await (let doc of legacy_docs.filter((d) => is_office_preview_ext(d.file_ext)).slice(0, 5)) {
+          await preview_drive_file(owner, doc);
+          done++;
+        }
+      }
+    }
+    return { code: 1, data: `previewed ${done}` };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// Called right after an upload so the preview is there in seconds rather than on the
+// next sweep. Deliberately tolerant: an unconvertible file must never fail its upload.
+export const generate_drive_file_preview = async (req) => {
+  try {
+    const { app_id, drive_type = 'user', uid, doc_id } = req || {};
+    if (!doc_id) return { code: -1, data: 'doc_id required' };
+
+    const project_id = drive_type === 'user' ? await get_account_default_project_id(uid) : await _common.get_project_app_id(app_id);
+    const ret = await db_module.get_app_couch_doc(project_id, doc_id);
+    const doc = ret?.code >= 0 ? ret.data : null;
+    if (!doc || doc.type !== 'file') return { code: -404, data: 'not_found' };
+    if (!is_office_preview_ext(doc.file_ext)) return { code: 1, data: 'not previewable' };
+
+    await preview_drive_file(drive_type === 'user' ? null : app_id, doc);
+    return { code: 1, data: { preview_stat: doc.preview_stat, preview_error: doc.preview_error || '' } };
+  } catch (err) {
+    return { code: -400, data: err.message };
+  }
+};
+
+// The links the UI needs, or nothing at all when there is no preview yet. Returned on
+// every drive row so a thumbnail and a lightbox can decide without a second call.
+//
+// preview_pending is the third answer, and it matters most right after an AI builds a
+// deck: the file is saved and its card renders in the chat within a second, while the
+// conversion behind it takes several. Without this the card can only say "no preview" and
+// mean "not yet", so it stayed a grey tile until the page was reloaded. Telling the client
+// a preview is coming lets it look again, and only for files that will actually get one.
+const preview_links_for = (doc, base_link) => {
+  const region = doc?.preview ? _pick_file_region({ bucket: doc.preview }) || Object.keys(doc.preview)[0] : null;
+  if (!region || !doc.preview[region]?.png) {
+    return [1, 2].includes(doc?.preview_stat) ? { preview_pending: true } : {};
+  }
+  const sep = base_link.includes('?') ? '&' : '?';
+  return {
+    preview_link: `${base_link}${sep}preview=png`,
+    preview_doc_link: `${base_link}${sep}preview=pdf`,
+  };
+};
+
 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');
@@ -2496,6 +2873,11 @@ export const run_drive_pending_ocr = async () => {
       // active/standby master pair double-run expensive OCR and race the writes.
       if (!_common.is_app_owned_by_local_box(app)) continue;
 
+      // Same dead-end as the preview sweep: ocr_stat 2 survives the restart that killed
+      // the run holding it, and nothing ever selects a 2 again.
+      await reclaim_stranded(app._id, 'user_drive', 'ocr_stat', 'ocr_stat_date');
+      await reclaim_stranded(app._id, 'workspace_drive', 'ocr_stat', 'ocr_stat_date');
+
       let opt = {
         selector: { docType: 'user_drive', ocr_stat: 1, stat: 3 },
         limit: 1,
@@ -3181,6 +3563,64 @@ export const get_user_drive_file = async function (uid, filename) {
   return drive_ret;
 };
 
+// Look a user-drive file up by the id in its access link, for surfaces that hold a
+// link and nothing else (an AI chat reply that produced a file, a pasted link). The
+// listing methods all key off a folder path, which a link does not carry.
+//
+// Returns the SAME row shape a listing child has, so a caller can hand it straight to
+// the drive thumbnail and lightbox. file_path is the point of the call: it is what
+// "Show in drive" needs to reveal the file, and it cannot be derived from the link.
+//
+// The lookup runs in the CALLER's own project (get_user_drive_file resolves the project
+// from the authenticated uid, never from anything the client sends), so a link into
+// someone else's drive answers not_found here. That is the honest answer: the file may
+// be readable over its link, but it is not in this user's drive and Show in drive has
+// nothing to reveal.
+export const get_user_drive_file_by_id = async (req) => {
+  try {
+    const uid = req.uid || req.token_ret?.data?.uid;
+    if (!uid) return { code: -1, data: 'uid_required' };
+
+    // Links may carry a cache-buster (?ts=) and are often pasted URL-encoded.
+    const raw = String(req.file_id || '').trim();
+    const file_id = decodeURIComponent(raw.split('?')[0].split('/').filter(Boolean).pop() || '');
+    if (!file_id) return { code: -1, data: 'file_id_required' };
+
+    const ret = await get_user_drive_file(uid, file_id);
+    const doc = ret?.code >= 0 ? ret.data : null;
+    if (!doc || doc.type !== 'file' || doc.stat === 4) return { code: -404, data: 'not_found' };
+
+    const app_id = await get_account_default_project_id(uid);
+    const fmt = (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 access_link = `https://${process.env.XUDA_HOSTNAME}/user-drive/${app_id}/${doc._id}`;
+
+    return {
+      code: 200,
+      data: {
+        name: doc.originalname,
+        sizeInBytes: doc.size,
+        size: fmt(doc.size),
+        extension: doc?.file_ext?.substr(1),
+        type: doc.type,
+        access_link,
+        ...preview_links_for(doc, access_link),
+        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) {
+    return { code: -404, data: 'not_found' };
+  }
+};
+
 // ── 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
@@ -3280,9 +3720,7 @@ export const read_site_file = async (req) => {
     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 { Bucket, Key } = _drive_bucket_for(d, region);
     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 }));
@@ -3691,6 +4129,23 @@ const _pick_file_region = (doc) => {
   return null;
 };
 
+// Where a drive doc's bytes actually live, for a given region.
+//
+// The CONFIG's bucket name wins over the one stored on the doc. Docs written before the
+// DigitalOcean to R2 migration still carry the old Spaces bucket in doc.bucket[region],
+// which no longer exists, so trusting the doc fails with "The specified bucket does not
+// exist" on files that serve perfectly well over https. The router has always resolved the
+// bucket from config alone (_presign_get), which is exactly why it can still read them;
+// this keeps every other reader consistent with the one that works. The doc's own name is
+// kept as a fallback for a region that config does not describe.
+const _drive_bucket_for = (doc, region) => {
+  const entry = (region && doc?.bucket?.[region]) || {};
+  return {
+    Bucket: (region && _conf.storage_bucket?.[region]?.name) || entry.Bucket || entry.bucket || null,
+    Key: entry.Key || entry.key || null,
+  };
+};
+
 const _stream_to_buffer = async (stream) => {
   if (!stream) return Buffer.alloc(0);
   // AWS SDK v3 Body is a Node Readable in this runtime.
@@ -3730,9 +4185,7 @@ export const read_user_drive_folder = async (req) => {
     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 { Bucket, Key } = _drive_bucket_for(d, region);
       const s3 = region ? _drive_s3_for(region) : null;
       if (!s3 || !Bucket || !Key) {
         // No reachable region (e.g. datacenter-scp file with no Spaces
@@ -3837,9 +4290,7 @@ export const fetch_drive_file_to_tmp = async (req) => {
     if (!doc) return { code: -1, data: `file not found: ${file_ref}` };
 
     const region = _pick_file_region(doc);
-    const b = (region && doc.bucket?.[region]) || {};
-    const Bucket = b.Bucket || b.bucket || (region && _conf.storage_bucket?.[region]?.name);
-    const Key = b.Key || b.key;
+    const { Bucket, Key } = _drive_bucket_for(doc, region);
     const s3 = region ? _drive_s3_for(region) : null;
     if (!s3 || !Bucket || !Key) return { code: -1, data: 'file bytes unavailable' };
 
@@ -4470,3 +4921,172 @@ export const file_upload_validator = function (file_name) {
       return { valid: false, error: `Unsupported file extension: .${ext}` };
   }
 };
+
+///////////////////////////////////////////////////////////////////////////////
+// DRIVE PLANS (UI-113)
+//
+// Drive is sold on its own drive_* ladder and what the ladder sells is SPACE.
+// A tier's `flags.extra_gb` is added on top of the storage the account already
+// has from its membership plan and its AI workspace plan, it does not replace
+// either, so an account that never picks a tier is on drive_free and nothing
+// about its Drive changes.
+//
+// The money is one line item on the consolidated subscription, the same shape
+// every other module tier uses: a paid tier creates or reprices the line, free
+// removes it. Billing moves FIRST and the plan is only written once Stripe
+// agreed, so a failed charge can never leave an account holding space it is
+// not paying for.
+///////////////////////////////////////////////////////////////////////////////
+
+const DRIVE_CATEGORY = 'drive';
+const GB = 1073741824;
+
+const _drive_tiers = () =>
+  Object.values(_conf.PLAN_OBJ || {})
+    .filter((p) => p.category === DRIVE_CATEGORY)
+    .sort((a, b) => (Number(a.rank) || 0) - (Number(b.rank) || 0));
+
+const _drive_plan = (plan_id) => {
+  const plan = _conf.PLAN_OBJ?.[plan_id];
+  return plan && plan.category === DRIVE_CATEGORY ? plan : null;
+};
+
+const _drive_account_doc = async (uid) => {
+  const ret = await db_module.get_couch_doc('xuda_accounts', uid);
+  return ret.code < 0 || !ret.data ? {} : ret.data;
+};
+
+// An account that never touched the ladder is on free. Same default the billing
+// Modules card applies, kept identical on purpose so the two never disagree.
+const _drive_account_plan = (account) => (_drive_plan(account?.drive_plan) ? account.drive_plan : 'drive_free');
+
+// What the account is storing, using the SAME sum the overage metering charges
+// on (account_module increment_account_usage). project_data_size is deliberately
+// out of it there, so it is out of it here: a guard that counted bytes the
+// metering ignores would refuse a downgrade the customer is not billed for.
+const _drive_used_bytes = (account) =>
+  (account?.user_drive_size || 0) +
+  (account?.studio_drive_size || 0) +
+  (account?.workspace_drive_size || 0) +
+  (account?.builds_drive_size || 0) +
+  (account?.plugins_drive_size || 0);
+
+// The quota the account WOULD have on a given tier, in bytes. Delegates to
+// account_module's get_effective_entitlements rather than re-deriving the stack,
+// because that function is what the metering and every storage bar already use.
+// Imported lazily: this is the only place in the drive module that needs it and
+// account_module pulls in a large tree of its own.
+const _drive_quota_bytes = async (account, plan_id) => {
+  const { get_effective_entitlements } = await import(`${module_path}/account_module/index.mjs`);
+  const ent = get_effective_entitlements({ ...account, drive_plan: plan_id ?? account?.drive_plan });
+  return {
+    unlimited: !Number.isFinite(ent.drive_gb),
+    bytes: Number.isFinite(ent.drive_gb) ? Math.round(ent.drive_gb * GB) : 0,
+    breakdown: ent.drive_breakdown || {},
+  };
+};
+
+const _drive_pretty = (bytes) => {
+  if (bytes >= 1099511627776) return `${Math.round((bytes / 1099511627776) * 10) / 10} TB`;
+  if (bytes >= GB) return `${Math.round((bytes / GB) * 10) / 10} GB`;
+  return `${Math.round(bytes / 1048576)} MB`;
+};
+
+export const get_drive_plans = async function (req) {
+  try {
+    const uid = req?.uid;
+    if (!uid) return { code: -401, data: 'not authenticated' };
+    const account = await _drive_account_doc(uid);
+    if (!account._id) return { code: -404, data: 'account not found' };
+
+    const plan_id = _drive_account_plan(account);
+    const used = _drive_used_bytes(account);
+    const quota = await _drive_quota_bytes(account, plan_id);
+
+    // Every tier carries the quota it WOULD give and whether the account already
+    // stores more than that, so the screen can mark a tier as out of reach
+    // without doing the entitlement arithmetic itself.
+    const plans = [];
+    for (const p of _drive_tiers()) {
+      const q = await _drive_quota_bytes(account, p.id);
+      plans.push({
+        ...p,
+        quota_bytes: q.bytes,
+        quota_unlimited: q.unlimited,
+        fits: q.unlimited || used <= q.bytes,
+      });
+    }
+
+    return {
+      code: 1,
+      data: {
+        plan_id,
+        plan_name: _drive_plan(plan_id)?.name || '',
+        changed_ts: account.drive_plan_changed || null,
+        // The line on the invoice. Free holds no item at all.
+        subscribed: !!account?.stripe_subscription_items?.[DRIVE_CATEGORY],
+        used_bytes: used,
+        quota_bytes: quota.bytes,
+        quota_unlimited: quota.unlimited,
+        // Where the space comes from, so a full bar can point at the plan that
+        // would actually fix it rather than at this one by default.
+        quota_from: {
+          membership_bytes: Math.round((quota.breakdown.membership_gb === Infinity ? 0 : quota.breakdown.membership_gb || 0) * GB),
+          workspace_bytes: Math.round((quota.breakdown.workspace_gb || 0) * GB),
+          drive_plan_bytes: Math.round((quota.breakdown.drive_plan_gb || 0) * GB),
+        },
+        membership_plan: account.membership_plan || 'free',
+        ai_workspace_plan: account.ai_workspace_plan || '',
+        plans,
+      },
+    };
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};
+
+export const drive_set_plan = async function (req) {
+  try {
+    const uid = req?.uid;
+    if (!uid) return { code: -401, data: 'not authenticated' };
+    const plan_id = req?.plan_id || '';
+    const plan = _drive_plan(plan_id);
+    if (!plan) return { code: -1, data: 'unknown drive plan' };
+
+    const account = await _drive_account_doc(uid);
+    if (!account._id) return { code: -404, data: 'account not found' };
+    const current = _drive_account_plan(account);
+    if (current === plan_id) return await get_drive_plans({ uid });
+
+    // Downgrade guard. Taking space away from an account that is already using it
+    // would drop it straight into metered overage on files it cannot see a way to
+    // remove, so name the gap instead and let the customer clear it first.
+    const target = await _drive_quota_bytes(account, plan_id);
+    const used = _drive_used_bytes(account);
+    if (!target.unlimited && used > target.bytes) {
+      return {
+        code: -1,
+        data: `You are storing ${_drive_pretty(used)} and the ${plan.name} plan would leave you with ${_drive_pretty(target.bytes)}. Free up ${_drive_pretty(used - target.bytes)} in Drive first.`,
+      };
+    }
+
+    const paid = Number(plan.price) > 0;
+    if (paid) {
+      const ret = await stripe_ms.add_subscription_item({ uid, plan_id });
+      if (!ret || ret.code < 0) return { code: ret?.code === -402 || ret?.code === -3 ? -402 : -1, data: ret?.data || 'could not change the plan' };
+    } else if (account.stripe_subscription_items?.[DRIVE_CATEGORY]) {
+      const ret = await stripe_ms.remove_subscription_item({ uid, category: DRIVE_CATEGORY });
+      if (!ret || ret.code < 0) return { code: -1, data: ret?.data || 'could not remove the subscription line' };
+    }
+
+    // Re-read: the stripe call just wrote stripe_subscription_items on this doc.
+    const fresh = await _drive_account_doc(uid);
+    fresh.drive_plan = plan_id;
+    fresh.drive_plan_changed = Date.now();
+    await db_module.save_couch_doc('xuda_accounts', fresh);
+
+    return await get_drive_plans({ uid });
+  } catch (err) {
+    return { code: -1, data: err.message || String(err) };
+  }
+};

package/index_ms.mjs

@@ -121,6 +121,14 @@ export const check_drive_file = async function (...args) {
   return await broker.send_to_queue("check_drive_file", ...args);
 };
 
+export const run_drive_pending_previews = async function (...args) {
+  return await broker.send_to_queue("run_drive_pending_previews", ...args);
+};
+
+export const generate_drive_file_preview = async function (...args) {
+  return await broker.send_to_queue("generate_drive_file_preview", ...args);
+};
+
 export const run_drive_pending_ocr = async function (...args) {
   return await broker.send_to_queue("run_drive_pending_ocr", ...args);
 };
@@ -153,6 +161,10 @@ export const update_drive_addons = async function (...args) {
   return await broker.send_to_queue("update_drive_addons", ...args);
 };
 
+export const get_user_drive_file_by_id = async function (...args) {
+  return await broker.send_to_queue("get_user_drive_file_by_id", ...args);
+};
+
 export const list_site_files = async function (...args) {
   return await broker.send_to_queue("list_site_files", ...args);
 };
@@ -421,6 +433,14 @@ export const file_upload_validator = async function (...args) {
   return await broker.send_to_queue("file_upload_validator", ...args);
 };
 
+export const get_drive_plans = async function (...args) {
+  return await broker.send_to_queue("get_drive_plans", ...args);
+};
+
+export const drive_set_plan = async function (...args) {
+  return await broker.send_to_queue("drive_set_plan", ...args);
+};
+
 export const get_drive_files_studio = async function (...args) {
   return await broker.send_to_queue("get_drive_files_studio", ...args);
 };

package/index_msa.mjs

@@ -121,6 +121,14 @@ export const check_drive_file =  function (...args) {
    broker.send_to_queue_async("check_drive_file", ...args);
 };
 
+export const run_drive_pending_previews =  function (...args) {
+   broker.send_to_queue_async("run_drive_pending_previews", ...args);
+};
+
+export const generate_drive_file_preview =  function (...args) {
+   broker.send_to_queue_async("generate_drive_file_preview", ...args);
+};
+
 export const run_drive_pending_ocr =  function (...args) {
    broker.send_to_queue_async("run_drive_pending_ocr", ...args);
 };
@@ -153,6 +161,10 @@ export const update_drive_addons =  function (...args) {
    broker.send_to_queue_async("update_drive_addons", ...args);
 };
 
+export const get_user_drive_file_by_id =  function (...args) {
+   broker.send_to_queue_async("get_user_drive_file_by_id", ...args);
+};
+
 export const list_site_files =  function (...args) {
    broker.send_to_queue_async("list_site_files", ...args);
 };
@@ -421,6 +433,14 @@ export const file_upload_validator =  function (...args) {
    broker.send_to_queue_async("file_upload_validator", ...args);
 };
 
+export const get_drive_plans =  function (...args) {
+   broker.send_to_queue_async("get_drive_plans", ...args);
+};
+
+export const drive_set_plan =  function (...args) {
+   broker.send_to_queue_async("drive_set_plan", ...args);
+};
+
 export const get_drive_files_studio =  function (...args) {
    broker.send_to_queue_async("get_drive_files_studio", ...args);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xuda.io/drive_module",
-  "version": "1.1.1499",
+  "version": "1.1.1501",
   "description": "Xuda Drive Server Module",
   "main": "index.mjs",
   "dependencies": {