stegdoc 4.0.0 → 5.0.0

package/src/lib/docx-templates.js

@@ -0,0 +1,355 @@
+/**
+ * Hebrew Incident Report Templates — Procedural Generation
+ *
+ * Uses component pools mixed via hash-seeded selection to produce
+ * thousands of unique report variants deterministically.
+ */
+
+// ─── Component Pools ────────────────────────────────────────────────────────
+
+const SERVICES = [
+  'שירות אימות',
+  'שירות API',
+  'שירות הזמנות',
+  'מערכת תשלומים',
+  'שירות התראות',
+  'שירות דוא"ל',
+  'שירות ניהול משתמשים',
+  'מערכת ניטור',
+  'שירות חיפוש',
+  'שירות סנכרון נתונים',
+  'שירות דוחות',
+  'מערכת לוגים',
+  'שירות קבצים',
+  'שירות תורים',
+  'מערכת ניהול תוכן',
+];
+
+const INCIDENT_TYPES = [
+  { type: 'זמני תגובה חריגים', category: 'perf' },
+  { type: 'כשל בחיבור לשרת מטמון', category: 'conn' },
+  { type: 'דליפת זיכרון בשרת ייצור', category: 'mem' },
+  { type: 'כשל בעדכון תעודת SSL', category: 'ssl' },
+  { type: 'עומס חריג בעקבות קמפיין שיווקי', category: 'load' },
+  { type: 'כשל בהתחברות לבסיס נתונים', category: 'conn' },
+  { type: 'שגיאות 500 חוזרות', category: 'err' },
+  { type: 'קריסת שירות בעקבות עדכון גרסה', category: 'deploy' },
+  { type: 'חסימת IP בעקבות חריגה ב-rate limit', category: 'load' },
+  { type: 'כשל בתהליך גיבוי אוטומטי', category: 'backup' },
+  { type: 'השהיה חריגה ב-DNS', category: 'perf' },
+  { type: 'שגיאת סנכרון בין שרתים', category: 'conn' },
+];
+
+const SUMMARIES = {
+  perf: [
+    'בשעות הבוקר התקבלה התרעה על עלייה חדה בזמני התגובה. צוות התשתיות פתח בחקירה ואיתר עומס חריג על שרת הנתונים הראשי. לאחר ניתוח הלוגים המצורפים, בוצעה הרחבת משאבים והשירות חזר לפעילות תקינה.',
+    'דווח על האטה משמעותית בזמני התגובה. בדיקה מעמיקה חשפה שאילתות כבדות שרצו ברקע ויצרו נעילות. הבעיה טופלה על ידי אופטימיזציה של השאילתות.',
+    'ניטור אוטומטי זיהה חריגה בזמני תגובה. החקירה העלתה בעיה בתצורת load balancer שהפנתה עומס לא אחיד בין השרתים.',
+  ],
+  conn: [
+    'דווחה בעיה בחיבוריות לרכיב חיצוני. בדיקה העלתה שחיבור נותק בעקבות עדכון תצורה שבוצע ללא תיאום מול צוות הפיתוח. השירות חזר לפעילות לאחר שיחזור התצורה הקודמת.',
+    'התקבלו דיווחים על כשלי חיבור מתמשכים. הבעיה אותרה בשינוי תצורת firewall שחסם פורט תקשורת פנימי. לאחר עדכון החוקים, השירות התייצב.',
+    'זוהתה בעיית קישוריות בין השירותים. הסיבה נמצאה בתעודת אימות שפגה תוקפה בין שני רכיבים פנימיים.',
+  ],
+  mem: [
+    'במהלך שעות הלילה אותרה דליפת זיכרון בשרת ייצור. הבעיה גרמה להאטה הדרגתית עד לקריסת השירות. צוות הכוננות ביצע הפעלה מחדש ופתח בחקירה.',
+    'צריכת זיכרון עלתה באופן מתמשך לאורך מספר שעות. הבעיה נגרמה מחיבורים שלא שוחררו כראוי במאגר החיבורים.',
+    'התרעת OOM (Out of Memory) התקבלה ממערכת הניטור. ניתוח ה-heap dump חשף אובייקטים שלא נאספו על ידי ה-GC עקב הפניות מעגליות.',
+  ],
+  ssl: [
+    'לקוחות דיווחו על שגיאות SSL בעת גישה לשירות. החקירה העלתה שתעודה פגה תוקף ולא חודשה אוטומטית. לאחר חידוש ידני, השירות חזר לפעילות.',
+    'התקבלו דיווחים על שגיאות אבטחה בחיבורים מאובטחים. הבעיה נבעה מתצורת TLS לא תואמת בין שירותים פנימיים.',
+  ],
+  load: [
+    'חלה עלייה חדה וחריגה בכמות הבקשות. השירות לא היה מוגדר לעמוד בעומס זה וחלק מהבקשות נדחו. בוצעה הרחבת משאבים אוטומטית.',
+    'בעקבות אירוע חיצוני, כמות הבקשות לשירות עלתה פי חמישה מהממוצע. חלק מההודעות הוכנסו לתור וטופלו באיחור.',
+    'זוהה עומס חריג שנגרם מתהליך batch שרץ בזמן שיא. הגבלת ה-rate limit הופעלה ומנעה עומס נוסף.',
+  ],
+  err: [
+    'התקבלו דיווחים על שגיאות 500 חוזרות מצד לקוחות. הבעיה אותרה בבאג בטיפול בבקשות לא תקינות שהוכנס בגרסה האחרונה.',
+    'מספר רב של שגיאות שרת נרשמו בלוגים. הסיבה נמצאה בכשל של שירות צד שלישי שלא טופל כראוי.',
+  ],
+  deploy: [
+    'לאחר פריסת גרסה חדשה, השירות החל להחזיר שגיאות. בוצע rollback מיידי לגרסה הקודמת והשירות התייצב.',
+    'עדכון גרסה גרם לאי-תאימות עם תצורת בסיס הנתונים. הבעיה אותרה ותוקנה על ידי migration שלא הופעל.',
+  ],
+  backup: [
+    'תהליך הגיבוי היומי נכשל ולא בוצע במשך 3 ימים. הבעיה נגרמה משינוי הרשאות על תיקיית היעד.',
+    'זוהה כשל בגיבוי אוטומטי. החקירה חשפה שנפח האחסון המיועד מלא ולא הוגדרה מדיניות מחיקה.',
+  ],
+};
+
+const TIMELINE_EVENTS = {
+  perf: [
+    [
+      { offset: 0, desc: 'התרעה ראשונה ממערכת ניטור — זמן תגובה חריג' },
+      { offset: 7, desc: 'צוות תשתיות מתחיל חקירה' },
+      { offset: 15, desc: 'זיהוי צוואר בקבוק — בדיקת לוגים' },
+      { offset: 25, desc: 'ביצוע פעולה מתקנת' },
+      { offset: 35, desc: 'זמני תגובה חוזרים לנורמה' },
+    ],
+    [
+      { offset: 0, desc: 'חריגה בזמני תגובה — ניטור מזהה' },
+      { offset: 5, desc: 'פתיחת חקירה' },
+      { offset: 12, desc: 'איתור שאילתות כבדות ברקע' },
+      { offset: 18, desc: 'עצירת תהליך רקע בעייתי' },
+      { offset: 22, desc: 'שירות חוזר לתקינות' },
+    ],
+  ],
+  conn: [
+    [
+      { offset: 0, desc: 'דיווח ראשון על שגיאות חיבור' },
+      { offset: 5, desc: 'זיהוי כשל — connection refused' },
+      { offset: 8, desc: 'בדיקת שינויים אחרונים בתצורה' },
+      { offset: 12, desc: 'שיחזור תצורה קודמת (rollback)' },
+      { offset: 15, desc: 'שירות חוזר לפעילות תקינה' },
+    ],
+    [
+      { offset: 0, desc: 'התרעה על כשל חיבור' },
+      { offset: 3, desc: 'בדיקת רשת ו-firewall' },
+      { offset: 10, desc: 'איתור חוק firewall חדש שחוסם תעבורה' },
+      { offset: 14, desc: 'עדכון חוקי firewall' },
+      { offset: 18, desc: 'חיבורים חוזרים, אימות תקינות' },
+    ],
+  ],
+  mem: [
+    [
+      { offset: 0, desc: 'צריכת זיכרון חוצה סף 70% — התרעה צהובה' },
+      { offset: 75, desc: 'צריכת זיכרון מגיעה ל-90% — התרעה אדומה' },
+      { offset: 134, desc: 'קריסת שירות — OOM Kill' },
+      { offset: 138, desc: 'כוננות מבצע הפעלה מחדש' },
+      { offset: 145, desc: 'שירות חוזר, ניטור מוגבר' },
+    ],
+  ],
+  ssl: [
+    [
+      { offset: 0, desc: 'דיווחים ראשונים — שגיאת SSL/TLS' },
+      { offset: 10, desc: 'זיהוי תעודה פגת תוקף' },
+      { offset: 15, desc: 'התחלת תהליך חידוש' },
+      { offset: 25, desc: 'תעודה חדשה הותקנה' },
+      { offset: 30, desc: 'אימות תקינות כל הנתיבים' },
+    ],
+  ],
+  load: [
+    [
+      { offset: 0, desc: 'עלייה חדה בכמות הבקשות' },
+      { offset: 5, desc: 'תור הודעות מתחיל להצטבר' },
+      { offset: 15, desc: 'שירות מחזיר שגיאות 429 (rate limit)' },
+      { offset: 30, desc: 'הגדלת משאבים (auto-scaling)' },
+      { offset: 60, desc: 'עומס מתייצב, כל הבקשות טופלו' },
+    ],
+  ],
+  err: [
+    [
+      { offset: 0, desc: 'דיווחים ראשונים על שגיאות שרת' },
+      { offset: 5, desc: 'בדיקת לוגים — זיהוי stack trace' },
+      { offset: 12, desc: 'זיהוי באג בגרסה האחרונה' },
+      { offset: 15, desc: 'ביצוע rollback לגרסה קודמת' },
+      { offset: 20, desc: 'שירות חוזר, שגיאות נעצרו' },
+    ],
+  ],
+  deploy: [
+    [
+      { offset: 0, desc: 'פריסת גרסה חדשה לייצור' },
+      { offset: 3, desc: 'זיהוי שגיאות לאחר הפריסה' },
+      { offset: 5, desc: 'החלטה על rollback' },
+      { offset: 8, desc: 'ביצוע rollback לגרסה קודמת' },
+      { offset: 12, desc: 'שירות יציב, פתיחת חקירה' },
+    ],
+  ],
+  backup: [
+    [
+      { offset: 0, desc: 'התרעה על כשל בגיבוי אוטומטי' },
+      { offset: 10, desc: 'בדיקת תיקיית יעד והרשאות' },
+      { offset: 20, desc: 'תיקון הרשאות / פינוי שטח' },
+      { offset: 25, desc: 'הפעלת גיבוי ידני — הצלחה' },
+      { offset: 30, desc: 'בדיקת תזמון גיבוי עתידי' },
+    ],
+  ],
+};
+
+const ROOT_CAUSES = {
+  perf: [
+    'שורש הבעיה אותר בשאילתת SQL לא מותאמת שרצה כחלק מתהליך סנכרון לילי ולא הסתיימה בזמן. השאילתה יצרה נעילה על טבלה מרכזית, מה שגרם להאטה משמעותית בכל הבקשות.',
+    'הבעיה נבעה מתצורת load balancer שלא עודכנה לאחר הוספת שרתים חדשים, מה שגרם לשרת יחיד לקבל את רוב העומס.',
+    'שאילתת חיפוש ללא אינדקס מתאים גרמה לסריקת טבלה מלאה, מה שהעמיס את בסיס הנתונים.',
+  ],
+  conn: [
+    'שינוי תצורה בוצע כחלק מתחזוקה שוטפת אך לא תואם מול צוות הפיתוח. השינוי גרם לכך שהשירותים לא הצליחו להתחבר לפורט החדש.',
+    'חוק firewall חדש שנוסף חסם תעבורה פנימית בין שני סגמנטים ברשת. החוק הופעל ללא בדיקה מוקדמת.',
+    'תעודת TLS mutual auth פגה תוקפה בין שני שירותים פנימיים ללא התרעה מוקדמת.',
+  ],
+  mem: [
+    'גרסה חדשה הכילה באג בניהול מאגר חיבורים — חיבורים לא שוחררו כראוי לאחר timeout. הבאג הוכנס בגרסה שפורסמה ימים קודם.',
+    'הפניות מעגליות בין אובייקטים מנעו את ה-GC מלשחרר זיכרון. הבעיה התגלתה רק תחת עומס גבוה.',
+    'מנגנון caching מקומי צבר נתונים ללא הגבלה ולא מימש מדיניות eviction.',
+  ],
+  ssl: [
+    'תהליך החידוש האוטומטי של certbot נכשל בעקבות שינוי הרשאות בתיקייה. השגיאה לא טופלה כי התרעת certbot לא הייתה מוגדרת.',
+    'עדכון תצורת TLS הוביל לאי-תאימות בין גרסת הפרוטוקול בצד השרת לבין הלקוח.',
+  ],
+  load: [
+    'השירות היה מוגדר למספר מצומצם של workers עם rate limit נמוך. אירוע חיצוני הכפיל את כמות הבקשות פי חמישה תוך דקות.',
+    'תהליך batch שתוזמן לרוץ בזמן שיא יצר עומס נוסף על שירות שכבר היה בעומס גבוה.',
+  ],
+  err: [
+    'באג בטיפול ב-edge case בבקשות API הוכנס בגרסה האחרונה. הבדיקות האוטומטיות לא כיסו את התרחיש הספציפי.',
+    'שירות צד שלישי שינה את פורמט התגובה ללא הודעה מראש, מה שגרם לשגיאות parsing.',
+  ],
+  deploy: [
+    'הפריסה כללה שינוי סכמה בבסיס הנתונים, אך ה-migration לא הופעל אוטומטית. השירות החדש ניסה לגשת לעמודות שלא קיימות.',
+    'תלות חדשה שנוספה דרשה משתנה סביבה שלא הוגדר בסביבת הייצור.',
+  ],
+  backup: [
+    'שינוי הרשאות על תיקיית הגיבוי מנע מתהליך האוטומטי לכתוב אליה. השינוי בוצע כחלק מהקשחת הרשאות.',
+    'נפח האחסון המיועד לגיבויים התמלא ולא הוגדרה מדיניות מחיקת גיבויים ישנים.',
+  ],
+};
+
+const RECOMMENDATIONS_POOL = [
+  // Performance
+  'הוספת אינדקסים לשאילתות כבדות שזוהו',
+  'הגדרת timeout מקסימלי לשאילתות ארוכות',
+  'הוספת התרעה על CPU מעל 80% בשרתי DB',
+  'תכנון מעבר שאילתות כבדות לרפליקת קריאה',
+  'עדכון תצורת load balancer לחלוקת עומס אחידה',
+  // Connectivity
+  'הטמעת תהליך Change Management לכל שינוי תשתיתי',
+  'הוספת health check אוטומטי לכל חיבורי שירות',
+  'הגדרת rollback אוטומטי בעת כשל health check',
+  'עדכון מערכת ניטור לזיהוי כשלי חיבור בזמן אמת',
+  'הגדרת circuit breaker לשירותים חיצוניים',
+  // Memory
+  'הגדרת restart אוטומטי בחריגת זיכרון מעל 85%',
+  'ביצוע code review מעמיק לשינויים בשכבת החיבורים',
+  'הוספת בדיקת עומס לתהליך CI/CD',
+  'הגדרת מדיניות eviction למנגנוני caching',
+  // SSL
+  'הגדרת ניטור לתוקף תעודות SSL — התרעה 30 יום לפני פקיעה',
+  'הוספת בדיקה יומית לתקינות certbot',
+  'הגדרת תעודת גיבוי (backup certificate)',
+  'תיעוד תהליך חידוש ידני ב-runbook',
+  // Load
+  'תיאום חובה בין שיווק/עסקים לפיתוח לפני כל אירוע',
+  'הגדרת auto-scaling לשירותים קריטיים',
+  'הגדלת rate limit בהתאם לקיבולת',
+  'הוספת תור עדיפויות — בקשות קריטיות מקבלות עדיפות',
+  // Errors / Deploy
+  'הרחבת כיסוי בדיקות אוטומטיות ל-edge cases',
+  'הוספת canary deployment לפני פריסה מלאה',
+  'הגדרת rollback אוטומטי בעת חריגה ב-error rate',
+  'בדיקת תאימות לאחור בתהליך הבדיקות',
+  // Backup
+  'הגדרת ניטור לתקינות גיבויים — התרעה על כשל',
+  'הגדרת מדיניות retention לגיבויים ישנים',
+  'ביצוע שחזור מדומה חודשי לבדיקת תקינות גיבויים',
+  // General
+  'עדכון runbook עם תהליך התמודדות מפורט',
+  'ביצוע תרגיל Incident Response רבעוני',
+  'הוספת דשבורד ניטור ייעודי לרכיב',
+];
+
+// ─── Seeded Random ──────────────────────────────────────────────────────────
+
+/**
+ * Simple deterministic PRNG from a hash string.
+ * Returns a function that yields numbers in [0, 1).
+ */
+function createRng(hash) {
+  let state = 0;
+  for (let i = 0; i < hash.length; i++) {
+    state = ((state << 5) - state + hash.charCodeAt(i)) | 0;
+  }
+  return function next() {
+    state = (state * 1664525 + 1013904223) | 0;
+    return ((state >>> 0) / 0x100000000);
+  };
+}
+
+function pick(rng, arr) {
+  return arr[Math.floor(rng() * arr.length)];
+}
+
+function pickN(rng, arr, n) {
+  const shuffled = [...arr];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled.slice(0, n);
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a unique incident report from a hash + part number.
+ * Different parts get different reports.
+ *
+ * @param {string} hash - File hash for deterministic selection
+ * @param {number} [partNumber=1] - Part number (each part gets a different variant)
+ * @returns {object} { title, summary, timeline, rootCause, recommendations }
+ */
+function generateIncident(hash, partNumber = 1) {
+  // Mix part number into seed so each part gets a different report
+  const seed = `${hash}_part${partNumber}`;
+  const rng = createRng(seed);
+
+  const service = pick(rng, SERVICES);
+  const incidentType = pick(rng, INCIDENT_TYPES);
+  const category = incidentType.category;
+
+  const title = `${service} — ${incidentType.type}`;
+
+  const summaryPool = SUMMARIES[category] || SUMMARIES.err;
+  const summary = pick(rng, summaryPool);
+
+  // Timeline
+  const timelinePool = TIMELINE_EVENTS[category] || TIMELINE_EVENTS.err;
+  const baseTimeline = pick(rng, timelinePool);
+
+  // Generate a start hour
+  const startHour = Math.floor(rng() * 20) + 1; // 01:00 - 20:00
+  const startMin = Math.floor(rng() * 4) * 15;  // 00, 15, 30, 45
+
+  const timeline = baseTimeline.map(evt => {
+    const totalMin = startHour * 60 + startMin + evt.offset;
+    const h = Math.floor(totalMin / 60) % 24;
+    const m = totalMin % 60;
+    return {
+      time: `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`,
+      desc: evt.desc,
+    };
+  });
+
+  const rootCausePool = ROOT_CAUSES[category] || ROOT_CAUSES.err;
+  const rootCause = pick(rng, rootCausePool);
+
+  // Pick 3-5 recommendations, mixing category-relevant and general
+  const numRecs = 3 + Math.floor(rng() * 3); // 3-5
+  const recommendations = pickN(rng, RECOMMENDATIONS_POOL, numRecs);
+
+  return { title, summary, timeline, rootCause, recommendations };
+}
+
+/**
+ * Generate a date string in Hebrew format.
+ * @param {string} hash - Hash for deterministic date
+ * @returns {string} Hebrew date string
+ */
+function generateHebrewDate(hash) {
+  const hashNum = parseInt(hash.slice(0, 8), 16) >>> 0;
+  const daysAgo = hashNum % 7;
+  const date = new Date(Date.now() - daysAgo * 24 * 60 * 60 * 1000);
+
+  const months = [
+    'ינואר', 'פברואר', 'מרץ', 'אפריל', 'מאי', 'יוני',
+    'יולי', 'אוגוסט', 'ספטמבר', 'אוקטובר', 'נובמבר', 'דצמבר',
+  ];
+
+  return `${date.getDate()} ב${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+
+module.exports = {
+  generateIncident,
+  generateHebrewDate,
+};

package/src/lib/file-handler.js

@@ -1,113 +1,113 @@
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Read a file and encode it to base64
- * @param {string} filePath - Path to the file
- * @returns {object} Object containing base64 string, filename, extension, and size
- */
-function encodeFileToBase64(filePath) {
-  if (!fs.existsSync(filePath)) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const stats = fs.statSync(filePath);
-
-  if (!stats.isFile()) {
-    throw new Error(`Path is not a file: ${filePath}`);
-  }
-
-  const fileBuffer = fs.readFileSync(filePath);
-  const base64 = fileBuffer.toString('base64');
-  const filename = path.basename(filePath);
-  const extension = path.extname(filePath);
-
-  return {
-    base64,
-    filename,
-    extension,
-    size: stats.size,
-  };
-}
-
-/**
- * Decode base64 string and write to file
- * @param {string} base64 - Base64 encoded string
- * @param {string} outputPath - Output file path
- */
-function decodeBase64ToFile(base64, outputPath) {
-  const buffer = Buffer.from(base64, 'base64');
-
-  // Ensure output directory exists
-  const outputDir = path.dirname(outputPath);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  fs.writeFileSync(outputPath, buffer);
-}
-
-/**
- * Split base64 string into chunks based on size limit
- * @param {string} base64 - Base64 string to split
- * @param {number} chunkSizeBytes - Maximum size per chunk in bytes
- * @returns {Array<string>} Array of base64 chunks
- */
-function splitBase64(base64, chunkSizeBytes) {
-  const chunks = [];
-  let offset = 0;
-
-  while (offset < base64.length) {
-    chunks.push(base64.slice(offset, offset + chunkSizeBytes));
-    offset += chunkSizeBytes;
-  }
-
-  return chunks;
-}
-
-/**
- * Merge base64 chunks back into a single string
- * @param {Array<string>} chunks - Array of base64 chunks
- * @returns {string} Merged base64 string
- */
-function mergeBase64Chunks(chunks) {
-  return chunks.join('');
-}
-
-/**
- * Calculate how many chunks will be needed for a file
- * @param {number} fileSize - File size in bytes
- * @param {number} chunkSizeBytes - Chunk size in bytes
- * @returns {number} Number of chunks needed
- */
-function calculateChunkCount(fileSize, chunkSizeBytes) {
-  // Base64 encoding increases size by ~33%
-  const base64Size = Math.ceil(fileSize * 4 / 3);
-  return Math.ceil(base64Size / chunkSizeBytes);
-}
-
-/**
- * Validate if a path is writable
- * @param {string} dirPath - Directory path to check
- * @returns {boolean} True if writable
- */
-function isDirectoryWritable(dirPath) {
-  try {
-    if (!fs.existsSync(dirPath)) {
-      fs.mkdirSync(dirPath, { recursive: true });
-    }
-    fs.accessSync(dirPath, fs.constants.W_OK);
-    return true;
-  } catch (error) {
-    return false;
-  }
-}
-
-module.exports = {
-  encodeFileToBase64,
-  decodeBase64ToFile,
-  splitBase64,
-  mergeBase64Chunks,
-  calculateChunkCount,
-  isDirectoryWritable,
-};
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read a file and encode it to base64
+ * @param {string} filePath - Path to the file
+ * @returns {object} Object containing base64 string, filename, extension, and size
+ */
+function encodeFileToBase64(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const stats = fs.statSync(filePath);
+
+  if (!stats.isFile()) {
+    throw new Error(`Path is not a file: ${filePath}`);
+  }
+
+  const fileBuffer = fs.readFileSync(filePath);
+  const base64 = fileBuffer.toString('base64');
+  const filename = path.basename(filePath);
+  const extension = path.extname(filePath);
+
+  return {
+    base64,
+    filename,
+    extension,
+    size: stats.size,
+  };
+}
+
+/**
+ * Decode base64 string and write to file
+ * @param {string} base64 - Base64 encoded string
+ * @param {string} outputPath - Output file path
+ */
+function decodeBase64ToFile(base64, outputPath) {
+  const buffer = Buffer.from(base64, 'base64');
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, buffer);
+}
+
+/**
+ * Split base64 string into chunks based on size limit
+ * @param {string} base64 - Base64 string to split
+ * @param {number} chunkSizeBytes - Maximum size per chunk in bytes
+ * @returns {Array<string>} Array of base64 chunks
+ */
+function splitBase64(base64, chunkSizeBytes) {
+  const chunks = [];
+  let offset = 0;
+
+  while (offset < base64.length) {
+    chunks.push(base64.slice(offset, offset + chunkSizeBytes));
+    offset += chunkSizeBytes;
+  }
+
+  return chunks;
+}
+
+/**
+ * Merge base64 chunks back into a single string
+ * @param {Array<string>} chunks - Array of base64 chunks
+ * @returns {string} Merged base64 string
+ */
+function mergeBase64Chunks(chunks) {
+  return chunks.join('');
+}
+
+/**
+ * Calculate how many chunks will be needed for a file
+ * @param {number} fileSize - File size in bytes
+ * @param {number} chunkSizeBytes - Chunk size in bytes
+ * @returns {number} Number of chunks needed
+ */
+function calculateChunkCount(fileSize, chunkSizeBytes) {
+  // Base64 encoding increases size by ~33%
+  const base64Size = Math.ceil(fileSize * 4 / 3);
+  return Math.ceil(base64Size / chunkSizeBytes);
+}
+
+/**
+ * Validate if a path is writable
+ * @param {string} dirPath - Directory path to check
+ * @returns {boolean} True if writable
+ */
+function isDirectoryWritable(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+    fs.accessSync(dirPath, fs.constants.W_OK);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = {
+  encodeFileToBase64,
+  decodeBase64ToFile,
+  splitBase64,
+  mergeBase64Chunks,
+  calculateChunkCount,
+  isDirectoryWritable,
+};