@yeyuan98/opencode-bioresearcher-plugin 1.7.0 → 1.7.1

package/dist/tools/table/backends/interface.d.ts

@@ -0,0 +1,68 @@
+export interface SheetInfo {
+    name: string;
+    index: number;
+}
+export interface ITableBackend {
+    readonly type: string;
+    listSheets(): SheetInfo[];
+    getHeaders(sheetIndex: number): {
+        headers: string[];
+        columnCount: number;
+    };
+    getTotalDataRows(sheetIndex: number): number;
+    getCell(sheetIndex: number, cellAddress: string): {
+        value: any;
+        type: string;
+    };
+    getRange(sheetIndex: number, range: string): {
+        data: any[][];
+        rows: number;
+        columns: number;
+        clamped_to?: string;
+        out_of_bounds?: boolean;
+    };
+    getPreview(sheetIndex: number, maxRows: number): {
+        rows: any[][];
+        totalRows: number;
+    };
+    search(sheetIndex: number, searchTerm: string, options: {
+        column?: string;
+        maxResults: number;
+        maxRowsScan: number;
+    }): {
+        results: any[];
+        totalMatchesFound: number;
+        rowsScanned: number;
+    };
+    filterRows(sheetIndex: number, column: string, operator: string, value: any, options: {
+        maxResults: number;
+        maxRowsScan: number;
+    }): {
+        matchedRows: Record<string, any>[];
+        totalMatchesFound: number;
+        totalDataRows: number;
+    };
+    summarize(sheetIndex: number, columns: string[] | undefined, options: {
+        maxRowsScan: number;
+    }): {
+        summaries: Record<string, any>;
+        rowCount: number;
+    };
+    groupBy(sheetIndex: number, groupColumn: string, aggColumn: string, aggType: string, options: {
+        maxRowsScan: number;
+    }): {
+        groups: Record<string, number>;
+    };
+    pivotSummary(sheetIndex: number, rowField: string, colField: string, valueField: string, agg: string, options: {
+        maxRowsScan: number;
+    }): {
+        columns: string[];
+        pivot: Record<string, Record<string, number>>;
+    };
+    dispose(): void;
+}
+export interface IWritableTableBackend extends ITableBackend {
+    appendRows(sheetIndex: number, rows: any[]): void;
+    updateCell(sheetIndex: number, cellAddress: string, value: any): void;
+    createFile(sheetName: string, data: any): void;
+}

package/dist/tools/table/backends/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/table/backends/xlsx/index.d.ts

@@ -0,0 +1,62 @@
+import { BaseTableBackend } from '../base';
+import type { IWritableTableBackend, SheetInfo } from '../interface';
+export declare class XLSXBackend extends BaseTableBackend implements IWritableTableBackend {
+    readonly type = "xlsx";
+    private workbook;
+    private sheetMap;
+    constructor(resolvedPath: string, force: boolean);
+    private getSheetData;
+    listSheets(): SheetInfo[];
+    getHeaders(sheetIndex: number): {
+        headers: string[];
+        columnCount: number;
+    };
+    getTotalDataRows(sheetIndex: number): number;
+    getCell(sheetIndex: number, cellAddress: string): {
+        value: any;
+        type: any;
+    };
+    getRange(sheetIndex: number, range: string): any;
+    getPreview(sheetIndex: number, maxRows: number): {
+        rows: any[][];
+        totalRows: number;
+    };
+    search(sheetIndex: number, searchTerm: string, options: {
+        column?: string;
+        maxResults: number;
+        maxRowsScan: number;
+    }): {
+        results: any[];
+        totalMatchesFound: number;
+        rowsScanned: number;
+    };
+    filterRows(sheetIndex: number, column: string, operator: string, value: any, options: {
+        maxResults: number;
+        maxRowsScan: number;
+    }): {
+        matchedRows: Record<string, any>[];
+        totalMatchesFound: number;
+        totalDataRows: number;
+    };
+    summarize(sheetIndex: number, columns: string[] | undefined, options: {
+        maxRowsScan: number;
+    }): {
+        summaries: Record<string, any>;
+        rowCount: number;
+    };
+    groupBy(sheetIndex: number, groupColumn: string, aggColumn: string, aggType: string, options: {
+        maxRowsScan: number;
+    }): {
+        groups: Record<string, number>;
+    };
+    pivotSummary(sheetIndex: number, rowField: string, colField: string, valueField: string, agg: string, options: {
+        maxRowsScan: number;
+    }): {
+        columns: string[];
+        pivot: Record<string, Record<string, number>>;
+    };
+    appendRows(sheetIndex: number, rows: any[]): void;
+    updateCell(sheetIndex: number, cellAddress: string, value: any): void;
+    createFile(sheetName: string, data: any): void;
+    dispose(): void;
+}

package/dist/tools/table/backends/xlsx/index.js

@@ -0,0 +1,547 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import * as XLSX from '../../../../vendor/xlsx.mjs';
+XLSX.set_fs(fs);
+import { BaseTableBackend } from '../base';
+import { iterativeMin, iterativeMax, DEFAULT_MAX_RANGE_CELLS } from '../../utils';
+const workbookCache = new Map();
+const MAX_CACHE_ENTRIES = 3;
+function getOrCacheWorkbook(resolvedPath, force) {
+    const stat = fs.statSync(resolvedPath);
+    const cached = workbookCache.get(resolvedPath);
+    if (cached && cached.mtimeMs === stat.mtimeMs) {
+        return cached.workbook;
+    }
+    const workbook = XLSX.readFile(resolvedPath);
+    workbookCache.set(resolvedPath, { workbook, mtimeMs: stat.mtimeMs });
+    if (workbookCache.size > MAX_CACHE_ENTRIES) {
+        const oldest = workbookCache.keys().next().value;
+        if (oldest !== undefined)
+            workbookCache.delete(oldest);
+    }
+    return workbook;
+}
+function invalidateCache(resolvedPath) {
+    workbookCache.delete(resolvedPath);
+}
+function convertExcelDate(excelDate) {
+    const daysSinceEpoch = excelDate - 25569;
+    const timestamp = daysSinceEpoch * 86400 * 1000;
+    const date = new Date(timestamp);
+    return date.toISOString().split('T')[0];
+}
+function processCellValue(cell) {
+    if (!cell)
+        return "";
+    switch (cell.t) {
+        case 'd': return convertExcelDate(cell.v);
+        case 'n': return cell.v;
+        case 'b': return cell.v;
+        case 's': return cell.v;
+        case 'e': return cell.w || cell.v;
+        case 'z': return "";
+        default: return cell.w || cell.v || "";
+    }
+}
+function getSheetDimensions(worksheet) {
+    const ref = worksheet['!ref'] ? XLSX.utils.decode_range(worksheet['!ref']) : null;
+    return ref
+        ? { startRow: ref.s.r, endRow: ref.e.r, startCol: ref.s.c, endCol: ref.e.c }
+        : { startRow: 0, endRow: 0, startCol: 0, endCol: 0 };
+}
+function deduplicateHeaders(rawHeaders) {
+    const headers = [];
+    const seen = new Map();
+    for (let i = 0; i < rawHeaders.length; i++) {
+        const raw = rawHeaders[i];
+        const count = seen.get(raw) ?? 0;
+        seen.set(raw, count + 1);
+        headers.push(count > 0 ? `${raw}_${count}` : raw);
+    }
+    return headers;
+}
+function getHeadersFromSheet(worksheet, dims) {
+    const rawHeaders = [];
+    for (let C = dims.startCol; C <= dims.endCol; C++) {
+        const addr = XLSX.utils.encode_cell({ r: dims.startRow, c: C });
+        const processed = processCellValue(worksheet[addr]);
+        const raw = (processed !== undefined && processed !== null && processed !== '') ? String(processed) : `Column_${C}`;
+        rawHeaders.push(raw);
+    }
+    return deduplicateHeaders(rawHeaders);
+}
+function rowToObject(worksheet, rowIdx, headers, startCol, endCol) {
+    const obj = {};
+    for (let C = startCol; C <= endCol; C++) {
+        const addr = XLSX.utils.encode_cell({ r: rowIdx, c: C });
+        const cell = worksheet[addr];
+        if (cell && cell.v !== undefined && cell.v !== null) {
+            obj[headers[C - startCol]] = cell.v;
+        }
+    }
+    return obj;
+}
+function getCellValue(worksheet, row, col) {
+    const cell = worksheet[XLSX.utils.encode_cell({ r: row, c: col })];
+    return processCellValue(cell);
+}
+function writeAtomic(workbook, filePath) {
+    const dir = path.dirname(filePath);
+    const suffix = crypto.randomBytes(8).toString('hex');
+    const tmpPath = path.join(dir, `.tmp_${suffix}_${path.basename(filePath)}`);
+    try {
+        XLSX.writeFile(workbook, tmpPath);
+        fs.renameSync(tmpPath, filePath);
+        invalidateCache(filePath);
+    }
+    catch (e) {
+        if (fs.existsSync(tmpPath)) {
+            fs.unlinkSync(tmpPath);
+        }
+        throw e;
+    }
+}
+const CELL_ADDRESS_REGEX = /^[A-Za-z]+\d+$/;
+export class XLSXBackend extends BaseTableBackend {
+    type = 'xlsx';
+    workbook;
+    sheetMap;
+    constructor(resolvedPath, force) {
+        super(resolvedPath, force);
+        this.workbook = getOrCacheWorkbook(resolvedPath, force);
+        this.sheetMap = new Map();
+    }
+    getSheetData(sheetIndex) {
+        const sheetName = this.workbook.SheetNames[sheetIndex];
+        if (!sheetName)
+            throw new Error(`Sheet index ${sheetIndex} out of range`);
+        if (!this.sheetMap.has(sheetName)) {
+            const worksheet = this.workbook.Sheets[sheetName];
+            const dims = getSheetDimensions(worksheet);
+            const headers = getHeadersFromSheet(worksheet, dims);
+            this.sheetMap.set(sheetName, { worksheet, dims, headers });
+        }
+        return this.sheetMap.get(sheetName);
+    }
+    listSheets() {
+        return this.workbook.SheetNames.map((name, i) => ({ name, index: i }));
+    }
+    getHeaders(sheetIndex) {
+        const sd = this.getSheetData(sheetIndex);
+        return { headers: sd.headers, columnCount: sd.headers.length };
+    }
+    getTotalDataRows(sheetIndex) {
+        const sd = this.getSheetData(sheetIndex);
+        return sd.dims.endRow - sd.dims.startRow;
+    }
+    getCell(sheetIndex, cellAddress) {
+        if (!CELL_ADDRESS_REGEX.test(cellAddress)) {
+            throw new Error(`Invalid cell address "${cellAddress}". Expected format like "A1", "B5", "AA123".`);
+        }
+        const sd = this.getSheetData(sheetIndex);
+        const cell = sd.worksheet[cellAddress];
+        const value = processCellValue(cell);
+        return { value, type: cell?.t || 'unknown' };
+    }
+    getRange(sheetIndex, range) {
+        const sd = this.getSheetData(sheetIndex);
+        const decoded = XLSX.utils.decode_range(range);
+        const requestedCells = (decoded.e.r - decoded.s.r + 1) * (decoded.e.c - decoded.s.c + 1);
+        if (!this.force && requestedCells > DEFAULT_MAX_RANGE_CELLS) {
+            throw new Error(`Range "${range}" exceeds ${DEFAULT_MAX_RANGE_CELLS} cell limit (${requestedCells} cells). Set force: true to override.`);
+        }
+        const sheetRef = sd.worksheet['!ref'] ? XLSX.utils.decode_range(sd.worksheet['!ref']) : null;
+        if (!sheetRef) {
+            return { data: [], rows: 0, columns: 0, out_of_bounds: true };
+        }
+        const clamped = {
+            s: { r: Math.max(decoded.s.r, sheetRef.s.r), c: Math.max(decoded.s.c, sheetRef.s.c) },
+            e: { r: Math.min(decoded.e.r, sheetRef.e.r), c: Math.min(decoded.e.c, sheetRef.e.c) },
+        };
+        if (clamped.s.r > clamped.e.r || clamped.s.c > clamped.e.c) {
+            return { data: [], rows: 0, columns: 0, out_of_bounds: true };
+        }
+        const data = [];
+        for (let R = clamped.s.r; R <= clamped.e.r; ++R) {
+            const row = [];
+            for (let C = clamped.s.c; C <= clamped.e.c; ++C) {
+                row.push(getCellValue(sd.worksheet, R, C));
+            }
+            data.push(row);
+        }
+        const result = {
+            data,
+            rows: data.length,
+            columns: data[0]?.length || 0,
+        };
+        if (clamped.s.r !== decoded.s.r || clamped.s.c !== decoded.s.c || clamped.e.r !== decoded.e.r || clamped.e.c !== decoded.e.c) {
+            result.clamped_to = XLSX.utils.encode_range(clamped);
+        }
+        return result;
+    }
+    getPreview(sheetIndex, maxRows) {
+        const sd = this.getSheetData(sheetIndex);
+        const previewRows = [];
+        for (let R = sd.dims.startRow; R <= sd.dims.endRow && previewRows.length < maxRows; R++) {
+            const row = [];
+            for (let C = sd.dims.startCol; C <= sd.dims.endCol; C++) {
+                row.push(getCellValue(sd.worksheet, R, C));
+            }
+            previewRows.push(row);
+        }
+        return { rows: previewRows, totalRows: sd.dims.endRow - sd.dims.startRow + 1 };
+    }
+    search(sheetIndex, searchTerm, options) {
+        const sd = this.getSheetData(sheetIndex);
+        const results = [];
+        let totalMatchesFound = 0;
+        let rowsScanned = 0;
+        const maxScanRow = Math.min(sd.dims.startRow + options.maxRowsScan, sd.dims.endRow);
+        if (options.column) {
+            const colIdx = sd.headers.indexOf(options.column);
+            if (colIdx === -1) {
+                throw new Error(`Column "${options.column}" not found. Available columns: ${sd.headers.slice(0, 20).join(', ')}${sd.headers.length > 20 ? ` ... (${sd.headers.length} total)` : ''}`);
+            }
+            const absCol = sd.dims.startCol + colIdx;
+            for (let R = sd.dims.startRow; R <= maxScanRow; ++R) {
+                rowsScanned++;
+                const cell = sd.worksheet[XLSX.utils.encode_cell({ r: R, c: absCol })];
+                if (cell && cell.v !== undefined) {
+                    const cellValue = String(processCellValue(cell)).toLowerCase();
+                    if (cellValue.includes(searchTerm.toLowerCase())) {
+                        totalMatchesFound++;
+                        if (results.length < options.maxResults) {
+                            const address = XLSX.utils.encode_cell({ r: R, c: absCol });
+                            results.push({ address, value: processCellValue(cell), type: cell.t || 'unknown', row_index: R, column: options.column });
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            for (let R = sd.dims.startRow; R <= maxScanRow; ++R) {
+                rowsScanned++;
+                for (let C = sd.dims.startCol; C <= sd.dims.endCol; ++C) {
+                    const address = XLSX.utils.encode_cell({ r: R, c: C });
+                    const cell = sd.worksheet[address];
+                    if (cell && cell.v !== undefined) {
+                        const cellValue = String(processCellValue(cell)).toLowerCase();
+                        if (cellValue.includes(searchTerm.toLowerCase())) {
+                            totalMatchesFound++;
+                            if (results.length < options.maxResults) {
+                                results.push({ address, value: processCellValue(cell), type: cell.t || 'unknown', row_index: R });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return { results, totalMatchesFound, rowsScanned };
+    }
+    filterRows(sheetIndex, column, operator, value, options) {
+        const sd = this.getSheetData(sheetIndex);
+        const filterColIdx = sd.headers.indexOf(column);
+        if (filterColIdx === -1) {
+            throw new Error(`Column "${column}" not found. Available columns: ${sd.headers.slice(0, 20).join(', ')}${sd.headers.length > 20 ? ` ... (${sd.headers.length} total)` : ''}`);
+        }
+        const filteredRows = [];
+        let totalMatchesFound = 0;
+        const maxScanRow = Math.min(sd.dims.startRow + options.maxRowsScan, sd.dims.endRow);
+        for (let R = sd.dims.startRow + 1; R <= maxScanRow; R++) {
+            const cellValue = getCellValue(sd.worksheet, R, sd.dims.startCol + filterColIdx);
+            let normalizedCell = cellValue;
+            let normalizedComp = value;
+            if (typeof normalizedCell === 'string' && normalizedCell.trim() !== '' && !isNaN(Number(normalizedCell))) {
+                normalizedCell = Number(normalizedCell);
+            }
+            if (typeof normalizedComp === 'string' && normalizedComp.trim() !== '' && !isNaN(Number(normalizedComp))) {
+                normalizedComp = Number(normalizedComp);
+            }
+            let matches = false;
+            switch (operator) {
+                case '=':
+                    matches = normalizedCell === normalizedComp;
+                    break;
+                case '!=':
+                    matches = normalizedCell !== normalizedComp;
+                    break;
+                case '>':
+                    matches = normalizedCell > normalizedComp;
+                    break;
+                case '<':
+                    matches = normalizedCell < normalizedComp;
+                    break;
+                case '>=':
+                    matches = normalizedCell >= normalizedComp;
+                    break;
+                case '<=':
+                    matches = normalizedCell <= normalizedComp;
+                    break;
+                case 'contains':
+                    matches = String(normalizedCell).toLowerCase().includes(String(normalizedComp).toLowerCase());
+                    break;
+                case 'starts_with':
+                    matches = String(normalizedCell).toLowerCase().startsWith(String(normalizedComp).toLowerCase());
+                    break;
+                case 'ends_with':
+                    matches = String(normalizedCell).toLowerCase().endsWith(String(normalizedComp).toLowerCase());
+                    break;
+            }
+            if (matches) {
+                totalMatchesFound++;
+                if (filteredRows.length < options.maxResults) {
+                    filteredRows.push(rowToObject(sd.worksheet, R, sd.headers, sd.dims.startCol, sd.dims.endCol));
+                }
+            }
+        }
+        return {
+            matchedRows: filteredRows,
+            totalMatchesFound,
+            totalDataRows: sd.dims.endRow - sd.dims.startRow,
+        };
+    }
+    summarize(sheetIndex, columns, options) {
+        const sd = this.getSheetData(sheetIndex);
+        const columnsToAnalyze = columns && columns.length > 0 ? columns : sd.headers;
+        const colStats = new Map();
+        for (const col of columnsToAnalyze) {
+            colStats.set(col, { n: 0, mean: 0, m2: 0, min: Infinity, max: -Infinity, sum: 0 });
+        }
+        const maxScanRow = Math.min(sd.dims.startRow + options.maxRowsScan, sd.dims.endRow);
+        for (let R = sd.dims.startRow + 1; R <= maxScanRow; R++) {
+            for (let ci = 0; ci < columnsToAnalyze.length; ci++) {
+                const colName = columnsToAnalyze[ci];
+                const colIdx = sd.headers.indexOf(colName);
+                if (colIdx === -1)
+                    continue;
+                const val = getCellValue(sd.worksheet, R, sd.dims.startCol + colIdx);
+                if (typeof val !== 'number' || isNaN(val))
+                    continue;
+                const s = colStats.get(colName);
+                s.n++;
+                s.sum += val;
+                if (val < s.min)
+                    s.min = val;
+                if (val > s.max)
+                    s.max = val;
+                const delta = val - s.mean;
+                s.mean += delta / s.n;
+                const delta2 = val - s.mean;
+                s.m2 += delta * delta2;
+            }
+        }
+        const summaries = {};
+        for (const col of columnsToAnalyze) {
+            const s = colStats.get(col);
+            if (s.n > 0) {
+                summaries[col] = { sum: s.sum, avg: s.mean, min: s.min, max: s.max, std_dev: Math.sqrt(s.m2 / s.n) };
+            }
+        }
+        const processedRows = maxScanRow - sd.dims.startRow;
+        return { summaries, rowCount: processedRows };
+    }
+    groupBy(sheetIndex, groupColumn, aggColumn, aggType, options) {
+        const sd = this.getSheetData(sheetIndex);
+        const groupColIdx = sd.headers.indexOf(groupColumn);
+        const aggColIdx = sd.headers.indexOf(aggColumn);
+        if (groupColIdx === -1)
+            throw new Error(`Group column "${groupColumn}" not found`);
+        if (aggColIdx === -1)
+            throw new Error(`Aggregation column "${aggColumn}" not found`);
+        const maxScanRow = Math.min(sd.dims.startRow + options.maxRowsScan, sd.dims.endRow);
+        const grouped = {};
+        for (let R = sd.dims.startRow + 1; R <= maxScanRow; R++) {
+            const groupKey = String(getCellValue(sd.worksheet, R, sd.dims.startCol + groupColIdx) || '');
+            const aggValue = getCellValue(sd.worksheet, R, sd.dims.startCol + aggColIdx);
+            if (!grouped[groupKey])
+                grouped[groupKey] = [];
+            if (aggType === 'count') {
+                grouped[groupKey].push(1);
+            }
+            else if (typeof aggValue === 'number' && !isNaN(aggValue)) {
+                grouped[groupKey].push(aggValue);
+            }
+        }
+        const result = {};
+        for (const groupKey of Object.keys(grouped)) {
+            const values = grouped[groupKey];
+            if (values.length === 0) {
+                result[groupKey] = 0;
+                continue;
+            }
+            switch (aggType) {
+                case 'sum':
+                    result[groupKey] = values.reduce((a, b) => a + b, 0);
+                    break;
+                case 'count':
+                    result[groupKey] = values.length;
+                    break;
+                case 'avg':
+                    result[groupKey] = values.reduce((a, b) => a + b, 0) / values.length;
+                    break;
+                case 'min': {
+                    const m = iterativeMin(values);
+                    result[groupKey] = m !== undefined ? m : 0;
+                    break;
+                }
+                case 'max': {
+                    const m = iterativeMax(values);
+                    result[groupKey] = m !== undefined ? m : 0;
+                    break;
+                }
+            }
+        }
+        return { groups: result };
+    }
+    pivotSummary(sheetIndex, rowField, colField, valueField, agg, options) {
+        const sd = this.getSheetData(sheetIndex);
+        const rowFieldIdx = sd.headers.indexOf(rowField);
+        const colFieldIdx = sd.headers.indexOf(colField);
+        const valueFieldIdx = sd.headers.indexOf(valueField);
+        if (rowFieldIdx === -1)
+            throw new Error(`Row field "${rowField}" not found`);
+        if (colFieldIdx === -1)
+            throw new Error(`Column field "${colField}" not found`);
+        if (valueFieldIdx === -1)
+            throw new Error(`Value field "${valueField}" not found`);
+        const maxScanRow = Math.min(sd.dims.startRow + options.maxRowsScan, sd.dims.endRow);
+        const pivot = {};
+        const counts = {};
+        const allCols = new Set();
+        for (let R = sd.dims.startRow + 1; R <= maxScanRow; R++) {
+            const rowKey = String(getCellValue(sd.worksheet, R, sd.dims.startCol + rowFieldIdx) || '');
+            const colKey = String(getCellValue(sd.worksheet, R, sd.dims.startCol + colFieldIdx) || '');
+            const value = getCellValue(sd.worksheet, R, sd.dims.startCol + valueFieldIdx);
+            allCols.add(colKey);
+            const isNumeric = typeof value === 'number' && !isNaN(value);
+            if (!isNumeric)
+                continue;
+            if (!pivot[rowKey])
+                pivot[rowKey] = {};
+            if (!counts[rowKey])
+                counts[rowKey] = {};
+            if (!pivot[rowKey][colKey]) {
+                if (agg === 'min')
+                    pivot[rowKey][colKey] = Infinity;
+                else if (agg === 'max')
+                    pivot[rowKey][colKey] = -Infinity;
+                else
+                    pivot[rowKey][colKey] = 0;
+            }
+            if (!counts[rowKey][colKey])
+                counts[rowKey][colKey] = 0;
+            counts[rowKey][colKey]++;
+            switch (agg) {
+                case 'sum':
+                case 'avg':
+                    pivot[rowKey][colKey] += value;
+                    break;
+                case 'min':
+                    pivot[rowKey][colKey] = Math.min(pivot[rowKey][colKey], value);
+                    break;
+                case 'max':
+                    pivot[rowKey][colKey] = Math.max(pivot[rowKey][colKey], value);
+                    break;
+                case 'count':
+                    pivot[rowKey][colKey]++;
+                    break;
+            }
+        }
+        if (agg === 'avg') {
+            for (const rowKey of Object.keys(pivot)) {
+                for (const colKey of Object.keys(pivot[rowKey])) {
+                    const count = counts[rowKey][colKey];
+                    if (count > 0)
+                        pivot[rowKey][colKey] /= count;
+                }
+            }
+        }
+        return { columns: Array.from(allCols).sort(), pivot };
+    }
+    appendRows(sheetIndex, rows) {
+        const sheetName = this.workbook.SheetNames[sheetIndex];
+        const worksheet = this.workbook.Sheets[sheetName];
+        if (rows.length > 0 && Array.isArray(rows[0])) {
+            XLSX.utils.sheet_add_aoa(worksheet, rows, { origin: -1 });
+        }
+        else {
+            const hasExistingData = !!worksheet['!ref'];
+            const header = hasExistingData ? undefined : Object.keys(rows[0] || {});
+            XLSX.utils.sheet_add_json(worksheet, rows, { origin: -1, header });
+        }
+        writeAtomic(this.workbook, this.resolvedPath);
+        this.sheetMap.delete(sheetName);
+    }
+    updateCell(sheetIndex, cellAddress, value) {
+        if (!CELL_ADDRESS_REGEX.test(cellAddress)) {
+            throw new Error(`Invalid cell address "${cellAddress}". Expected format like "A1", "B5", "AA123".`);
+        }
+        const sheetName = this.workbook.SheetNames[sheetIndex];
+        const worksheet = this.workbook.Sheets[sheetName];
+        if (value === null) {
+            delete worksheet[cellAddress];
+        }
+        else {
+            let cellType;
+            if (typeof value === 'number')
+                cellType = 'n';
+            else if (typeof value === 'boolean')
+                cellType = 'b';
+            else
+                cellType = 's';
+            worksheet[cellAddress] = { v: value, t: cellType };
+        }
+        const newCellAddr = XLSX.utils.decode_cell(cellAddress);
+        const currentRef = worksheet['!ref'];
+        if (currentRef) {
+            const currentRange = XLSX.utils.decode_range(currentRef);
+            if (newCellAddr.r > currentRange.e.r || newCellAddr.c > currentRange.e.c) {
+                const maxReasonableRow = Math.max(currentRange.e.r + 1000, newCellAddr.r);
+                const maxReasonableCol = Math.max(currentRange.e.c + 26, newCellAddr.c);
+                const updatedRange = {
+                    s: { r: Math.min(currentRange.s.r, newCellAddr.r), c: Math.min(currentRange.s.c, newCellAddr.c) },
+                    e: { r: Math.min(Math.max(currentRange.e.r, newCellAddr.r), maxReasonableRow), c: Math.min(Math.max(currentRange.e.c, newCellAddr.c), maxReasonableCol) },
+                };
+                worksheet['!ref'] = XLSX.utils.encode_range(updatedRange);
+            }
+        }
+        else {
+            worksheet['!ref'] = XLSX.utils.encode_range({ s: newCellAddr, e: newCellAddr });
+        }
+        writeAtomic(this.workbook, this.resolvedPath);
+        this.sheetMap.delete(sheetName);
+    }
+    createFile(sheetName, data) {
+        if (fs.existsSync(this.resolvedPath)) {
+            invalidateCache(this.resolvedPath);
+        }
+        const workbook = XLSX.utils.book_new();
+        let worksheet;
+        let parsedData = data;
+        if (typeof parsedData === 'string') {
+            try {
+                parsedData = JSON.parse(parsedData);
+            }
+            catch (e) {
+                throw new Error(`Failed to parse data string as JSON: ${e}`);
+            }
+        }
+        if (!Array.isArray(parsedData))
+            throw new Error(`Data must be an array, received: ${typeof parsedData}`);
+        if (parsedData.length === 0) {
+            worksheet = XLSX.utils.aoa_to_sheet([]);
+        }
+        else if (Array.isArray(parsedData[0])) {
+            worksheet = XLSX.utils.aoa_to_sheet(parsedData);
+        }
+        else {
+            worksheet = XLSX.utils.json_to_sheet(parsedData);
+        }
+        XLSX.utils.book_append_sheet(workbook, worksheet, sheetName);
+        writeAtomic(workbook, this.resolvedPath);
+    }
+    dispose() {
+        this.sheetMap.clear();
+    }
+}