onbuzz 4.8.2 → 4.9.0

package/src/tools/office/officePres.js

@@ -0,0 +1,360 @@
+/**
+ * officePres — PowerPoint (.pptx) builder for officeTool.
+ *
+ * Built on pptxgenjs. Supports the slide surface an agent needs to
+ * deliver a polished deck without hand-crafting XML:
+ *   - Layouts: 16:9 (default), 16:10, 4:3, wide, plus custom dimensions
+ *   - Theme: background colour, primary + accent colour, default font
+ *   - Slide masters (header band + footer footer / page number)
+ *   - Per-slide background colour or image
+ *   - Slide types: title / content / two-content / section-header /
+ *     table / chart / blank — but we accept any layout and treat the
+ *     layout as a hint for default placements
+ *   - Content items: text, bullets, images, tables, shapes, charts
+ *   - Speaker notes
+ *   - Slide transitions and slide numbers
+ *
+ * Reader is a stub (PPTX read is rare and pptx-parser support is
+ * inconsistent across runtimes). info returns slide count + titles
+ * via JSZip-based extraction.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { createRequire } from 'module';
+
+// pptxgenjs ships dual builds (ESM + CJS). The ESM build does
+// `import JSZip from 'jszip'` which jszip (CJS-only) does not satisfy
+// cleanly under jest's experimental-vm-modules. Loading via createRequire
+// resolves the CJS build, which is well-behaved in both Node and Jest.
+const localRequire = createRequire(import.meta.url);
+
+let pptxgen = null;
+let JSZip = null;
+
+function loadPptx() {
+  if (pptxgen) return pptxgen;
+  const mod = localRequire('pptxgenjs');
+  pptxgen = mod.default || mod;
+  return pptxgen;
+}
+
+function loadZip() {
+  if (JSZip) return JSZip;
+  // jszip is a transitive dep of pptxgenjs, available at runtime.
+  JSZip = localRequire('jszip');
+  return JSZip;
+}
+
+function normHex(v) {
+  if (!v || typeof v !== 'string') return null;
+  const s = v.replace(/^#/, '').trim().toUpperCase();
+  return /^[0-9A-F]{6}$/.test(s) ? s : null;
+}
+
+function resolveLayout(pptx, layout) {
+  if (!layout) return 'LAYOUT_WIDE';
+  if (typeof layout === 'object' && layout.width && layout.height) {
+    // Custom: register a layout name and return it.
+    pptx.defineLayout({
+      name: 'CUSTOM_LAYOUT',
+      width: Number(layout.width),
+      height: Number(layout.height),
+    });
+    return 'CUSTOM_LAYOUT';
+  }
+  const k = String(layout).toUpperCase();
+  switch (k) {
+    case '16:9':
+    case '16X9':
+    case 'WIDE':
+    case 'LAYOUT_WIDE':
+      return 'LAYOUT_WIDE';
+    case '16:10':
+    case '16X10':
+    case 'LAYOUT_16X10':
+      return 'LAYOUT_16x10';
+    case '4:3':
+    case '4X3':
+    case 'STANDARD':
+    case 'LAYOUT_4X3':
+      return 'LAYOUT_4x3';
+    default:
+      return 'LAYOUT_WIDE';
+  }
+}
+
+/** Convert a text-style object → pptxgenjs text options. */
+function textOpts(style = {}, defaults = {}) {
+  const out = {
+    fontFace: style.fontFace || style.font || defaults.fontFace,
+    fontSize: Number(style.fontSize) || defaults.fontSize || 18,
+    bold: !!style.bold,
+    italic: !!style.italic,
+    underline: style.underline ? { style: 'sng' } : undefined,
+    align: style.align || 'left',
+    valign: style.valign || 'top',
+  };
+  const hex = normHex(style.color || defaults.color);
+  if (hex) out.color = hex;
+  const fill = normHex(style.fill);
+  if (fill) out.fill = { color: fill };
+  return out;
+}
+
+function placeItem(slide, item, defaults) {
+  const at = { x: item.x ?? 0.5, y: item.y ?? 0.5, w: item.w ?? 9, h: item.h ?? 1 };
+  switch ((item.type || '').toLowerCase()) {
+    case 'text':
+      slide.addText(item.text || '', { ...at, ...textOpts(item, defaults) });
+      break;
+
+    case 'bullets':
+    case 'bullet-list':
+    case 'list': {
+      const items = (item.items || []).map(li => {
+        if (typeof li === 'string') return { text: li, options: { bullet: true } };
+        return {
+          text: li.text || '',
+          options: {
+            bullet: li.bullet === false ? false : { type: li.ordered ? 'number' : 'bullet' },
+            indentLevel: li.level || 0,
+          },
+        };
+      });
+      slide.addText(items, {
+        ...at,
+        ...textOpts(item, defaults),
+        paraSpaceAfter: item.spacing ?? 6,
+      });
+      break;
+    }
+
+    case 'image': {
+      const src = item.path || item.data;
+      if (!src) break;
+      slide.addImage({ ...at, [item.data ? 'data' : 'path']: src });
+      break;
+    }
+
+    case 'table': {
+      const rows = [];
+      if (Array.isArray(item.headers) && item.headers.length > 0) {
+        rows.push(item.headers.map(h => ({
+          text: String(h),
+          options: {
+            bold: true,
+            color: normHex(item.headerStyle?.color) || 'FFFFFF',
+            fill: { color: normHex(item.headerStyle?.fill) || '1F3864' },
+            align: 'left',
+          },
+        })));
+      }
+      for (const row of item.rows || []) {
+        if (Array.isArray(row)) {
+          rows.push(row.map(c => ({
+            text: String(c ?? ''),
+            options: { color: normHex(item.cellStyle?.color) || '202020' },
+          })));
+        }
+      }
+      slide.addTable(rows, {
+        ...at,
+        colW: item.colW,
+        rowH: item.rowH,
+        fontSize: item.fontSize || 12,
+        border: item.border === false ? undefined : { type: 'solid', pt: 0.5, color: 'CCCCCC' },
+      });
+      break;
+    }
+
+    case 'shape': {
+      const shape = (item.shape || 'rect').toLowerCase();
+      const map = {
+        rect: 'rect', rectangle: 'rect',
+        rounded: 'roundRect', 'rounded-rect': 'roundRect',
+        oval: 'ellipse', ellipse: 'ellipse',
+        line: 'line',
+        triangle: 'triangle',
+      };
+      const shapeId = map[shape] || 'rect';
+      slide.addShape(shapeId, {
+        ...at,
+        fill: normHex(item.fill) ? { color: normHex(item.fill) } : undefined,
+        line: normHex(item.border)
+          ? { color: normHex(item.border), width: item.borderWidth || 1 }
+          : undefined,
+      });
+      break;
+    }
+
+    case 'chart': {
+      const chartTypeMap = {
+        bar: 'bar', column: 'bar',
+        line: 'line',
+        pie: 'pie',
+        doughnut: 'doughnut',
+        area: 'area',
+      };
+      const type = chartTypeMap[(item.chartType || 'bar').toLowerCase()] || 'bar';
+      slide.addChart(type, item.data || [], {
+        ...at,
+        showTitle: !!item.title,
+        title: item.title || '',
+      });
+      break;
+    }
+
+    default:
+      // Treat unknown items as plain text so the deck never crashes.
+      slide.addText(item.text || '', { ...at, ...textOpts(item, defaults) });
+  }
+}
+
+/* ------------------------------------------------------------------------ */
+/* Public API                                                                */
+/* ------------------------------------------------------------------------ */
+
+export async function createPres(spec, outputPath) {
+  const Pptx = loadPptx();
+  const pptx = new Pptx();
+
+  pptx.title = spec.title || '';
+  pptx.subject = spec.subject || '';
+  pptx.author = spec.author || 'Loxia Agent';
+  pptx.company = spec.company || '';
+  pptx.layout = resolveLayout(pptx, spec.layout);
+
+  const theme = spec.theme || {};
+  const defaults = {
+    fontFace: theme.fontFamily || 'Calibri',
+    fontSize: theme.fontSize || 18,
+    color: normHex(theme.textColor) || '202020',
+  };
+  const themeBg = normHex(theme.background);
+  const primary = normHex(theme.primaryColor) || '1F3864';
+  const accent = normHex(theme.accentColor) || '2E75B6';
+
+  // Slide master: title bar + footer with page number.
+  if (spec.useMaster !== false) {
+    pptx.defineSlideMaster({
+      title: 'LOXIA_MASTER',
+      background: themeBg ? { color: themeBg } : { color: 'FFFFFF' },
+      objects: [
+        { rect: { x: 0, y: 0, w: '100%', h: 0.35, fill: { color: primary } } },
+        {
+          text: {
+            text: spec.title || '',
+            options: { x: 0.4, y: 0.05, w: 8, h: 0.3, fontSize: 12, color: 'FFFFFF', bold: true, fontFace: defaults.fontFace },
+          },
+        },
+        {
+          placeholder: {
+            options: { name: 'footer', type: 'body', x: 0.4, y: '95%', w: 5, h: 0.3, fontSize: 9, color: '707070' },
+            text: spec.company || '',
+          },
+        },
+        { rect: { x: 0, y: '99.4%', w: '100%', h: 0.06, fill: { color: accent } } },
+      ],
+      slideNumber: { x: '93%', y: '95%', fontSize: 9, color: '707070' },
+    });
+  }
+
+  const slides = Array.isArray(spec.slides) ? spec.slides : [];
+  for (const slideDef of slides) {
+    const slide = pptx.addSlide({ masterName: spec.useMaster !== false ? 'LOXIA_MASTER' : undefined });
+
+    // Per-slide background override
+    const slideBg = normHex(slideDef.background);
+    if (slideBg) slide.background = { color: slideBg };
+
+    // Speaker notes
+    if (slideDef.notes) slide.addNotes(String(slideDef.notes));
+
+    // Default placements by layout
+    const layout = (slideDef.layout || 'content').toLowerCase();
+
+    if (layout === 'section-header' || layout === 'section') {
+      if (slideDef.title) {
+        slide.addText(slideDef.title, {
+          x: 0.5, y: 2.0, w: 9, h: 1.5,
+          fontSize: 40, bold: true, color: primary, fontFace: defaults.fontFace, align: 'left',
+        });
+      }
+      if (slideDef.subtitle) {
+        slide.addText(slideDef.subtitle, {
+          x: 0.5, y: 3.5, w: 9, h: 0.8,
+          fontSize: 20, color: '595959', fontFace: defaults.fontFace, align: 'left',
+        });
+      }
+    } else if (layout === 'title' || layout === 'title-slide') {
+      if (slideDef.title) {
+        slide.addText(slideDef.title, {
+          x: 0.5, y: 1.5, w: 9, h: 1.5,
+          fontSize: 44, bold: true, color: primary, fontFace: defaults.fontFace, align: 'center',
+        });
+      }
+      if (slideDef.subtitle) {
+        slide.addText(slideDef.subtitle, {
+          x: 0.5, y: 3.2, w: 9, h: 0.8,
+          fontSize: 20, italic: true, color: '595959', fontFace: defaults.fontFace, align: 'center',
+        });
+      }
+    } else {
+      // Default content layout — title at top, body fills the rest.
+      if (slideDef.title) {
+        slide.addText(slideDef.title, {
+          x: 0.5, y: 0.5, w: 9, h: 0.7,
+          fontSize: 28, bold: true, color: primary, fontFace: defaults.fontFace, align: 'left',
+        });
+      }
+      if (slideDef.subtitle) {
+        slide.addText(slideDef.subtitle, {
+          x: 0.5, y: 1.15, w: 9, h: 0.4,
+          fontSize: 14, italic: true, color: '595959', fontFace: defaults.fontFace, align: 'left',
+        });
+      }
+    }
+
+    // Place any free-form content items
+    for (const item of slideDef.content || []) {
+      placeItem(slide, item, defaults);
+    }
+
+    // Slide transition (pptxgenjs accepts addNotes only; transitions need
+    // raw XML hacks — skipped for now). Slide-number override:
+    if (slideDef.slideNumber === false) slide.slideNumber = { x: -1, y: -1 };
+  }
+
+  // pptxgenjs writeFile uses its own filename mechanism; we capture buffer instead.
+  const buf = await pptx.write({ outputType: 'nodebuffer' });
+  await fs.writeFile(outputPath, buf);
+  const stat = await fs.stat(outputPath);
+  return { path: outputPath, size: stat.size, slideCount: slides.length };
+}
+
+/* ----- info (light reader via JSZip) ----- */
+
+export async function presInfo(filePath) {
+  const stat = await fs.stat(filePath);
+  // Count slides by listing entries in the pptx zip.
+  try {
+    const Zip = loadZip();
+    const buf = await fs.readFile(filePath);
+    const zip = await Zip.loadAsync(buf);
+    const slidePaths = Object.keys(zip.files).filter(p => /^ppt\/slides\/slide\d+\.xml$/.test(p));
+    return {
+      fileName: path.basename(filePath),
+      fileSize: stat.size,
+      modified: stat.mtime.toISOString(),
+      slideCount: slidePaths.length,
+    };
+  } catch {
+    return {
+      fileName: path.basename(filePath),
+      fileSize: stat.size,
+      modified: stat.mtime.toISOString(),
+      slideCount: null,
+    };
+  }
+}

package/src/tools/office/officeSheet.js

@@ -0,0 +1,350 @@
+/**
+ * officeSheet — Excel (.xlsx) builder + reader for officeTool.
+ *
+ * Builder supports the rich-spreadsheet surface our agents need:
+ *   - Multiple sheets per workbook with names, tabColor, default font
+ *   - Typed columns (text/number/currency/percent/date/duration) with
+ *     header style, number format, width, auto-size hints
+ *   - Header styling block: bold, fill, fontColor, alignment, height,
+ *     wrapText
+ *   - Alternating row fill (zebra) for readability
+ *   - Per-cell styling via cellStyles array
+ *   - Formulas via { cell, formula } OR inline "=A1+B1" strings in rows
+ *   - Merged cells
+ *   - Freeze panes (row + column)
+ *   - Auto-filter
+ *   - Conditional formatting (cellIs, containsText, dataBar, colorScale)
+ *   - Named ranges
+ *   - Charts — line / bar / pie (limited by exceljs surface)
+ *
+ * All input is permissively normalised; unknown column type → text.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+let ExcelJS = null;
+async function loadExcel() {
+  if (ExcelJS) return ExcelJS;
+  const mod = await import('exceljs');
+  ExcelJS = mod.default || mod;
+  return ExcelJS;
+}
+
+function normHex(v) {
+  if (!v || typeof v !== 'string') return null;
+  const s = v.replace(/^#/, '').trim().toUpperCase();
+  return /^[0-9A-F]{6}$/.test(s) ? s : null;
+}
+
+function argb(hex) {
+  const h = normHex(hex);
+  return h ? `FF${h}` : null;
+}
+
+function numFmtForType(type) {
+  switch ((type || '').toLowerCase()) {
+    case 'number':   return '#,##0';
+    case 'integer':  return '0';
+    case 'currency': return '$#,##0.00';
+    case 'percent':  return '0.0%';
+    case 'date':     return 'yyyy-mm-dd';
+    case 'datetime': return 'yyyy-mm-dd hh:mm';
+    case 'duration': return '[h]:mm:ss';
+    default:         return null;
+  }
+}
+
+function colLetter(n) {
+  let s = '';
+  while (n > 0) {
+    const r = (n - 1) % 26;
+    s = String.fromCharCode(65 + r) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+
+/** Apply a style object onto a cell: { bold, italic, fontColor, fill, alignment, wrapText }. */
+function applyCellStyle(cell, style) {
+  if (!style) return;
+  const font = { ...(cell.font || {}) };
+  if (style.bold != null) font.bold = !!style.bold;
+  if (style.italic != null) font.italic = !!style.italic;
+  if (style.underline) font.underline = true;
+  const colorHex = argb(style.fontColor);
+  if (colorHex) font.color = { argb: colorHex };
+  if (style.fontName) font.name = style.fontName;
+  if (style.fontSize) font.size = Number(style.fontSize);
+  cell.font = font;
+
+  const fillHex = argb(style.fill);
+  if (fillHex) {
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: fillHex } };
+  }
+  if (style.alignment || style.wrapText != null) {
+    cell.alignment = {
+      ...(cell.alignment || {}),
+      horizontal: style.alignment || cell.alignment?.horizontal,
+      wrapText: style.wrapText ?? cell.alignment?.wrapText,
+    };
+  }
+  if (style.border) {
+    const colour = argb(style.borderColor) || 'FFCCCCCC';
+    cell.border = {
+      top:    { style: 'thin', color: { argb: colour } },
+      bottom: { style: 'thin', color: { argb: colour } },
+      left:   { style: 'thin', color: { argb: colour } },
+      right:  { style: 'thin', color: { argb: colour } },
+    };
+  }
+}
+
+/* ------------------------------------------------------------------------ */
+/* Public API                                                                */
+/* ------------------------------------------------------------------------ */
+
+export async function createSheet(spec, outputPath) {
+  const Excel = await loadExcel();
+  const workbook = new Excel.Workbook();
+  workbook.creator = spec.creator || 'Loxia Agent';
+  workbook.created = new Date();
+  if (spec.properties) {
+    Object.assign(workbook, {
+      title: spec.properties.title || '',
+      subject: spec.properties.subject || '',
+      company: spec.properties.company || '',
+    });
+  }
+
+  const sheets = Array.isArray(spec.sheets) ? spec.sheets : [];
+  if (sheets.length === 0) {
+    throw new Error('createSheet requires at least one sheet definition');
+  }
+
+  for (const sheetDef of sheets) {
+    const ws = workbook.addWorksheet(sheetDef.name || 'Sheet', {
+      properties: {
+        tabColor: argb(sheetDef.tabColor) ? { argb: argb(sheetDef.tabColor) } : undefined,
+      },
+    });
+
+    // Columns
+    if (Array.isArray(sheetDef.columns) && sheetDef.columns.length > 0) {
+      ws.columns = sheetDef.columns.map(col => {
+        const key = col.key || (col.header || '').toLowerCase().replace(/\s+/g, '_') || 'col';
+        return {
+          header: col.header || '',
+          key,
+          width: col.width || 15,
+          style: col.numFmt || col.type ? { numFmt: col.numFmt || numFmtForType(col.type) || undefined } : undefined,
+        };
+      });
+    }
+
+    // Header style
+    if (sheetDef.headerStyle && ws.columns?.length > 0) {
+      const headerRow = ws.getRow(1);
+      headerRow.eachCell(cell => applyCellStyle(cell, sheetDef.headerStyle));
+      if (sheetDef.headerStyle.height) headerRow.height = sheetDef.headerStyle.height;
+    }
+
+    // Rows. Inline "=..." strings are converted to formula cells.
+    const altFill = argb(sheetDef.alternateRowFill);
+    if (Array.isArray(sheetDef.rows)) {
+      sheetDef.rows.forEach((row, idx) => {
+        const isArr = Array.isArray(row);
+        const added = ws.addRow(row);
+        if (altFill && idx % 2 === 1) {
+          added.eachCell(cell => {
+            cell.fill = cell.fill || { type: 'pattern', pattern: 'solid', fgColor: { argb: altFill } };
+          });
+        }
+        if (isArr) {
+          row.forEach((val, i) => {
+            if (typeof val === 'string' && val.startsWith('=')) {
+              added.getCell(i + 1).value = { formula: val.slice(1) };
+            }
+          });
+        } else if (typeof row === 'object' && row) {
+          for (const [k, v] of Object.entries(row)) {
+            if (typeof v === 'string' && v.startsWith('=')) {
+              const colIdx = (ws.columns || []).findIndex(c => c.key === k);
+              if (colIdx >= 0) added.getCell(colIdx + 1).value = { formula: v.slice(1) };
+            }
+          }
+        }
+      });
+    }
+
+    // Explicit formulas
+    if (Array.isArray(sheetDef.formulas)) {
+      for (const f of sheetDef.formulas) {
+        if (!f.cell || !f.formula) continue;
+        const c = ws.getCell(f.cell);
+        c.value = { formula: f.formula.startsWith('=') ? f.formula.slice(1) : f.formula };
+      }
+    }
+
+    // Per-cell styles
+    if (Array.isArray(sheetDef.cellStyles)) {
+      for (const cs of sheetDef.cellStyles) {
+        if (!cs.cell) continue;
+        applyCellStyle(ws.getCell(cs.cell), cs.style || cs);
+      }
+    }
+
+    // Merged cells
+    if (Array.isArray(sheetDef.mergedCells)) {
+      for (const m of sheetDef.mergedCells) {
+        if (m.range) ws.mergeCells(m.range);
+        else if (m.from && m.to) ws.mergeCells(`${m.from}:${m.to}`);
+      }
+    }
+
+    // Freeze panes
+    if (sheetDef.freezeRow || sheetDef.freezeColumn) {
+      ws.views = [{
+        state: 'frozen',
+        xSplit: sheetDef.freezeColumn || 0,
+        ySplit: sheetDef.freezeRow || 0,
+      }];
+    }
+
+    // Auto-filter
+    if (sheetDef.autoFilter && ws.columns?.length > 0) {
+      const last = ws.columnCount;
+      ws.autoFilter = typeof sheetDef.autoFilter === 'object'
+        ? sheetDef.autoFilter
+        : { from: 'A1', to: `${colLetter(last)}1` };
+    }
+
+    // Conditional formatting
+    if (Array.isArray(sheetDef.conditionalFormatting)) {
+      for (const cf of sheetDef.conditionalFormatting) {
+        if (!cf.range || !cf.type) continue;
+        ws.addConditionalFormatting({
+          ref: cf.range,
+          rules: [buildCfRule(cf)],
+        });
+      }
+    }
+
+    // Named ranges
+    if (Array.isArray(sheetDef.namedRanges)) {
+      for (const nr of sheetDef.namedRanges) {
+        if (nr.name && nr.range) {
+          workbook.definedNames.add(`${ws.name}!${nr.range}`, nr.name);
+        }
+      }
+    }
+
+    // Charts — best-effort. exceljs has limited chart support; we skip if the
+    // exceljs version doesn't expose addChart. Returning the spec in metadata
+    // so renderers/callers can know the chart was requested.
+    if (Array.isArray(sheetDef.charts) && typeof ws.addChart === 'function') {
+      for (const c of sheetDef.charts) {
+        try { ws.addChart(c); } catch { /* unsupported; skip */ }
+      }
+    }
+  }
+
+  await workbook.xlsx.writeFile(outputPath);
+  const stat = await fs.stat(outputPath);
+  return { path: outputPath, size: stat.size, sheetCount: sheets.length };
+}
+
+function buildCfRule(cf) {
+  const style = {
+    font: cf.fontColor ? { color: { argb: argb(cf.fontColor) } } : undefined,
+    fill: cf.fill ? { type: 'pattern', pattern: 'solid', bgColor: { argb: argb(cf.fill) } } : undefined,
+  };
+  switch ((cf.type || '').toLowerCase()) {
+    case 'cellis':
+    case 'cell-is':
+      return {
+        type: 'cellIs',
+        operator: cf.operator || 'greaterThan',
+        formulae: Array.isArray(cf.formulae) ? cf.formulae : [String(cf.value ?? 0)],
+        style,
+      };
+    case 'containstext':
+    case 'contains-text':
+      return { type: 'containsText', operator: 'containsText', text: cf.text || '', style };
+    case 'databar':
+    case 'data-bar':
+      return { type: 'dataBar', cfvo: [{ type: 'min' }, { type: 'max' }], color: { argb: argb(cf.color) || 'FF638EC6' } };
+    case 'colorscale':
+    case 'color-scale':
+      return {
+        type: 'colorScale',
+        cfvo: [{ type: 'min' }, { type: 'percentile', value: 50 }, { type: 'max' }],
+        color: [
+          { argb: argb(cf.min) || 'FFF8696B' },
+          { argb: argb(cf.mid) || 'FFFFEB84' },
+          { argb: argb(cf.max) || 'FF63BE7B' },
+        ],
+      };
+    default:
+      return { type: 'expression', formulae: [cf.formula || 'FALSE'], style };
+  }
+}
+
+/* ----- read / info ----- */
+
+export async function readSheet(filePath, opts = {}) {
+  const Excel = await loadExcel();
+  const workbook = new Excel.Workbook();
+  if (filePath.toLowerCase().endsWith('.csv')) {
+    await workbook.csv.readFile(filePath);
+  } else {
+    await workbook.xlsx.readFile(filePath);
+  }
+  const sheetName = opts.sheetName;
+  const ws = sheetName ? workbook.getWorksheet(sheetName) : workbook.worksheets[0];
+  if (!ws) {
+    const available = workbook.worksheets.map(w => w.name);
+    throw new Error(`Sheet not found${sheetName ? `: ${sheetName}` : ''}. Available: ${available.join(', ') || '(none)'}`);
+  }
+  const totalRows = ws.actualRowCount || ws.rowCount;
+  const startRow = Math.max(1, opts.startRow || 1);
+  const endRow = opts.endRow ? Math.min(opts.endRow, totalRows) : totalRows;
+  const rows = [];
+  for (let r = startRow; r <= endRow; r++) {
+    const row = ws.getRow(r);
+    const out = [];
+    for (let c = 1; c <= ws.columnCount; c++) {
+      const cell = row.getCell(c);
+      if (opts.includeFormulas && cell.formula) out.push(`=${cell.formula}`);
+      else out.push(cell.value ?? '');
+    }
+    rows.push(out);
+  }
+  return { sheetName: ws.name, rows, startRow, endRow, totalRows };
+}
+
+export async function sheetInfo(filePath) {
+  const Excel = await loadExcel();
+  const workbook = new Excel.Workbook();
+  if (filePath.toLowerCase().endsWith('.csv')) {
+    await workbook.csv.readFile(filePath);
+  } else {
+    await workbook.xlsx.readFile(filePath);
+  }
+  const sheets = [];
+  workbook.eachSheet(ws => {
+    sheets.push({
+      name: ws.name,
+      rowCount: ws.actualRowCount || ws.rowCount,
+      columnCount: ws.columnCount,
+    });
+  });
+  const stat = await fs.stat(filePath);
+  return {
+    fileName: path.basename(filePath),
+    fileSize: stat.size,
+    modified: stat.mtime.toISOString(),
+    sheetCount: sheets.length,
+    sheets,
+  };
+}