starmux 0.12.0 → 0.13.0

package/dist/vendor/desktop-commander/dist/utils/files/excel.js

@@ -0,0 +1,497 @@
+/**
+ * Excel file handler using ExcelJS
+ * Handles reading, writing, and editing Excel files (.xlsx, .xls, .xlsm)
+ */
+import fs from 'fs/promises';
+import { createRequire } from 'module';
+import { LazyPackage } from '../lazy-package.js';
+const require = createRequire(import.meta.url);
+// require(), not import(): Node keeps a failed import() failed, so it couldn't load again
+export const exceljsPackage = new LazyPackage('exceljs', 'Excel support', () => require('exceljs'));
+async function newWorkbook() {
+    return new (exceljsPackage.load().Workbook)();
+}
+// File size limit: 10MB
+const FILE_SIZE_LIMIT = 10 * 1024 * 1024;
+/**
+ * Excel file handler implementation using ExcelJS
+ * Supports: .xlsx, .xls, .xlsm files
+ */
+export class ExcelFileHandler {
+    canHandle(path) {
+        const ext = path.toLowerCase();
+        return ext.endsWith('.xlsx') || ext.endsWith('.xls') || ext.endsWith('.xlsm');
+    }
+    async read(path, options) {
+        await this.checkFileSize(path);
+        const workbook = await newWorkbook();
+        await workbook.xlsx.readFile(path);
+        const metadata = await this.extractMetadata(workbook, path);
+        const { sheetName, data, totalRows, returnedRows, firstRow } = this.worksheetToArray(workbook, options?.sheet, options?.range, options?.offset, options?.length);
+        // Format output with sheet info header, usage hint, and JSON data.
+        // No rows while there are some means the offset starts past the end.
+        const paginationInfo = totalRows <= returnedRows
+            ? ''
+            : returnedRows > 0
+                ? `\n[Showing rows ${firstRow}-${firstRow + returnedRows - 1} of ${totalRows} total. Use offset/length to paginate.]`
+                : `\n[No rows returned: row ${firstRow} is past the end (${totalRows} rows total). Use offset/length to paginate.]`;
+        const sheetHasSpace = /\s/.test(sheetName);
+        const exampleSheet = sheetHasSpace ? sheetName : 'Sheet1';
+        const content = `[Sheet: '${sheetName}' from ${path}]${paginationInfo}
+[To MODIFY cells: use edit_block with range param, e.g., edit_block(path, {range: "${exampleSheet}!E5", content: [[newValue]]}). read_file accepts the same range form, or pass sheet + range separately.]
+
+${JSON.stringify(data)}`;
+        return {
+            content,
+            mimeType: 'application/json',
+            metadata: {
+                isExcelFile: true,
+                sheets: metadata.sheets,
+                fileSize: metadata.fileSize,
+                isLargeFile: metadata.isLargeFile
+            }
+        };
+    }
+    async write(path, content, mode) {
+        // Check existing file size if it exists
+        try {
+            await this.checkFileSize(path);
+        }
+        catch (error) {
+            // File doesn't exist - that's fine for write
+            if (error.code !== 'ENOENT' &&
+                !(error instanceof Error && error.message.includes('ENOENT'))) {
+                throw error;
+            }
+        }
+        // Parse content
+        let parsedContent = content;
+        if (typeof content === 'string') {
+            try {
+                parsedContent = JSON.parse(content);
+            }
+            catch {
+                throw new Error('Invalid content format. Expected JSON string with 2D array or object with sheet names.');
+            }
+        }
+        // Handle append mode by finding last row and writing after it
+        if (mode === 'append') {
+            try {
+                const workbook = await newWorkbook();
+                await workbook.xlsx.readFile(path);
+                if (Array.isArray(parsedContent)) {
+                    // Append to Sheet1, or to the first sheet of a workbook without one
+                    let worksheet = workbook.getWorksheet('Sheet1') ?? workbook.worksheets[0];
+                    if (!worksheet) {
+                        worksheet = workbook.addWorksheet('Sheet1');
+                    }
+                    const startRow = this.dataExtent(worksheet).lastRow + 1;
+                    this.writeRowsStartingAt(worksheet, startRow, parsedContent);
+                }
+                else if (typeof parsedContent === 'object' && parsedContent !== null) {
+                    // Append to each named sheet
+                    for (const [sheetName, data] of Object.entries(parsedContent)) {
+                        if (Array.isArray(data)) {
+                            let worksheet = workbook.getWorksheet(sheetName);
+                            if (!worksheet) {
+                                worksheet = workbook.addWorksheet(sheetName);
+                            }
+                            const startRow = this.dataExtent(worksheet).lastRow + 1;
+                            this.writeRowsStartingAt(worksheet, startRow, data);
+                        }
+                    }
+                }
+                await workbook.xlsx.writeFile(path);
+                return;
+            }
+            catch (error) {
+                // File doesn't exist - fall through to create new file
+                if (error.code !== 'ENOENT' &&
+                    !(error instanceof Error && error.message.includes('ENOENT'))) {
+                    throw error;
+                }
+            }
+        }
+        // Rewrite mode (or append to non-existent file): create new workbook
+        const workbook = await newWorkbook();
+        if (Array.isArray(parsedContent)) {
+            // Single sheet from 2D array
+            this.writeDataToSheet(workbook, 'Sheet1', parsedContent);
+        }
+        else if (typeof parsedContent === 'object' && parsedContent !== null) {
+            // Object with sheet names as keys
+            for (const [sheetName, data] of Object.entries(parsedContent)) {
+                if (Array.isArray(data)) {
+                    this.writeDataToSheet(workbook, sheetName, data);
+                }
+            }
+        }
+        else {
+            throw new Error('Invalid content format. Expected 2D array or object with sheet names.');
+        }
+        await workbook.xlsx.writeFile(path);
+    }
+    async editRange(path, range, content, options) {
+        // Verify file exists and check size
+        try {
+            await this.checkFileSize(path);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' ||
+                (error instanceof Error && error.message.includes('ENOENT'))) {
+                throw new Error(`File not found: ${path}`);
+            }
+            throw error;
+        }
+        // Validate content
+        if (!Array.isArray(content)) {
+            throw new Error('Content must be a 2D array for range editing');
+        }
+        // Parse range: "Sheet1!A1:C10" or "Sheet1"
+        const [sheetName, cellRange] = this.parseRange(range);
+        const workbook = await newWorkbook();
+        await workbook.xlsx.readFile(path);
+        // Get or create sheet
+        let worksheet = workbook.getWorksheet(sheetName);
+        if (!worksheet) {
+            worksheet = workbook.addWorksheet(sheetName);
+        }
+        if (cellRange) {
+            // Write to specific range
+            const { startRow, startCol, endRow, endCol } = this.parseCellRange(cellRange);
+            // A FROM:TO range bounds the write: content that doesn't fit is refused
+            // before any cell changes, so no cell outside the range is overwritten
+            if (endRow !== undefined && endCol !== undefined) {
+                const rows = content.length;
+                const columns = Math.max(0, ...content.map((row) => Array.isArray(row) ? row.length : 0));
+                const rangeRows = endRow - startRow + 1;
+                const rangeColumns = endCol - startCol + 1;
+                if (rows > rangeRows || columns > rangeColumns) {
+                    throw new Error(`Content has ${rows} row(s) and ${columns} column(s) but range ${cellRange} holds ` +
+                        `${rangeRows} row(s) and ${rangeColumns} column(s); nothing was written`);
+                }
+            }
+            for (let r = 0; r < content.length; r++) {
+                const rowData = content[r];
+                if (!Array.isArray(rowData))
+                    continue;
+                for (let c = 0; c < rowData.length; c++) {
+                    const cell = worksheet.getCell(startRow + r, startCol + c);
+                    const value = rowData[c];
+                    if (typeof value === 'string' && value.startsWith('=')) {
+                        cell.value = { formula: value.substring(1) };
+                    }
+                    else {
+                        cell.value = value;
+                    }
+                }
+            }
+        }
+        else {
+            // Replace entire sheet content
+            // Clear existing data
+            worksheet.eachRow((row, rowNumber) => {
+                row.eachCell((cell) => {
+                    cell.value = null;
+                });
+            });
+            // Write new data
+            for (let r = 0; r < content.length; r++) {
+                const rowData = content[r];
+                if (!Array.isArray(rowData))
+                    continue;
+                const row = worksheet.getRow(r + 1);
+                for (let c = 0; c < rowData.length; c++) {
+                    const value = rowData[c];
+                    if (typeof value === 'string' && value.startsWith('=')) {
+                        row.getCell(c + 1).value = { formula: value.substring(1) };
+                    }
+                    else {
+                        row.getCell(c + 1).value = value;
+                    }
+                }
+                row.commit();
+            }
+        }
+        await workbook.xlsx.writeFile(path);
+        return { success: true, editsApplied: 1 };
+    }
+    async getInfo(path) {
+        const stats = await fs.stat(path);
+        try {
+            const workbook = await newWorkbook();
+            await workbook.xlsx.readFile(path);
+            const metadata = await this.extractMetadata(workbook, path);
+            return {
+                size: stats.size,
+                created: stats.birthtime,
+                modified: stats.mtime,
+                accessed: stats.atime,
+                isDirectory: stats.isDirectory(),
+                isFile: stats.isFile(),
+                permissions: stats.mode.toString(8).slice(-3),
+                fileType: 'excel',
+                metadata: {
+                    isExcelFile: true,
+                    sheets: metadata.sheets,
+                    fileSize: metadata.fileSize,
+                    isLargeFile: metadata.isLargeFile
+                }
+            };
+        }
+        catch (error) {
+            return {
+                size: stats.size,
+                created: stats.birthtime,
+                modified: stats.mtime,
+                accessed: stats.atime,
+                isDirectory: stats.isDirectory(),
+                isFile: stats.isFile(),
+                permissions: stats.mode.toString(8).slice(-3),
+                fileType: 'excel',
+                metadata: {
+                    isExcelFile: true,
+                    fileSize: stats.size,
+                    error: true,
+                    errorMessage: error instanceof Error ? error.message : String(error)
+                }
+            };
+        }
+    }
+    // ========== Private Helpers ==========
+    async checkFileSize(path) {
+        const stats = await fs.stat(path);
+        if (stats.size > FILE_SIZE_LIMIT) {
+            const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
+            throw new Error(`Excel file size (${sizeMB}MB) exceeds 10MB limit. ` +
+                `Consider using specialized tools for large file processing.`);
+        }
+    }
+    async extractMetadata(workbook, path) {
+        const stats = await fs.stat(path);
+        const sheets = workbook.worksheets.map(ws => {
+            const { lastRow, lastCol } = this.dataExtent(ws);
+            return { name: ws.name, rowCount: lastRow, colCount: lastCol };
+        });
+        return {
+            sheets,
+            fileSize: stats.size,
+            isLargeFile: stats.size > FILE_SIZE_LIMIT
+        };
+    }
+    /**
+     * The last row and the last column holding a value (0 for an empty sheet):
+     * where the sheet's data ends, for reads, sheet info and appends alike.
+     * Not actualRowCount/actualColumnCount: those COUNT the used rows and
+     * columns, so data in columns A and AH only would end at column B.
+     */
+    dataExtent(worksheet) {
+        let lastRow = 0;
+        let lastCol = 0;
+        worksheet.eachRow((row, rowNumber) => {
+            lastRow = rowNumber;
+            row.eachCell((_cell, colNumber) => {
+                lastCol = Math.max(lastCol, colNumber);
+            });
+        });
+        return { lastRow, lastCol };
+    }
+    worksheetToArray(workbook, sheetRef, range, offset, length) {
+        if (workbook.worksheets.length === 0) {
+            return { sheetName: '', data: [], totalRows: 0, returnedRows: 0, firstRow: 1 };
+        }
+        // `sheet` is a name or a 0-based index as a string ("0"). A number that is
+        // no sheet's index but a sheet's name ("2024") means that sheet.
+        if (typeof sheetRef === 'string' && /^\d+$/.test(sheetRef)
+            && (Number(sheetRef) < workbook.worksheets.length || !workbook.getWorksheet(sheetRef))) {
+            sheetRef = Number(sheetRef);
+        }
+        // Accept range with embedded sheet prefix (parity with edit_block).
+        // E.g. range:"Sheet1!A1:B2" or "'My Sheet'!A1" — strip the sheet
+        // prefix and, when the caller did not pass an explicit sheet, use it.
+        let cellRangeOnly = range;
+        if (range && range.includes('!')) {
+            const [sheetFromRange, cellsFromRange] = this.parseRange(range);
+            cellRangeOnly = cellsFromRange ?? undefined;
+            if (sheetRef === undefined && sheetFromRange) {
+                sheetRef = sheetFromRange;
+            }
+        }
+        // Find target worksheet
+        let worksheet;
+        let sheetName;
+        if (sheetRef === undefined) {
+            worksheet = workbook.worksheets[0];
+            sheetName = worksheet.name;
+        }
+        else if (typeof sheetRef === 'number') {
+            if (sheetRef < 0 || sheetRef >= workbook.worksheets.length) {
+                throw new Error(`Sheet index ${sheetRef} out of range (0-${workbook.worksheets.length - 1})`);
+            }
+            worksheet = workbook.worksheets[sheetRef];
+            sheetName = worksheet.name;
+        }
+        else {
+            worksheet = workbook.getWorksheet(sheetRef);
+            if (!worksheet) {
+                const available = workbook.worksheets.map(ws => ws.name).join(', ');
+                throw new Error(`Sheet "${sheetRef}" not found. Available sheets: ${available}`);
+            }
+            sheetName = sheetRef;
+        }
+        // Determine range to read: from A1 to the last cell of the data
+        const { lastRow, lastCol } = this.dataExtent(worksheet);
+        let startRow = 1;
+        let endRow = lastRow || 1;
+        let startCol = 1;
+        let endCol = lastCol || 1;
+        if (cellRangeOnly) {
+            const parsed = this.parseCellRange(cellRangeOnly);
+            startRow = parsed.startRow;
+            startCol = parsed.startCol;
+            if (parsed.endRow)
+                endRow = parsed.endRow;
+            if (parsed.endCol)
+                endCol = parsed.endCol;
+        }
+        // Calculate total rows before pagination. A single cell reads to the end
+        // of the data, so one below the data (A10 on a 5-row sheet) has no rows,
+        // and one right of it (Z1 on a sheet ending at column C) has no cells.
+        const totalRows = startCol > endCol ? 0 : Math.max(0, endRow - startRow + 1);
+        const rangeStartRow = startRow;
+        // Apply offset/length pagination (row-based, matching text file behavior)
+        if (offset !== undefined) {
+            if (offset < 0) {
+                // Negative offset: last N rows (like text files)
+                // offset: -10 means "last 10 rows"
+                const lastNRows = Math.abs(offset);
+                startRow = Math.max(startRow, endRow - lastNRows + 1);
+            }
+            else if (offset > 0) {
+                // Positive offset: skip first N rows
+                startRow = startRow + offset;
+            }
+        }
+        // Apply length limit (only for positive offset or no offset)
+        if (length !== undefined && length > 0 && (offset === undefined || offset >= 0)) {
+            endRow = Math.min(endRow, startRow + length - 1);
+        }
+        // 1-based position of the first returned row within the totalRows,
+        // taken from the pagination actually applied (not the raw offset)
+        const firstRow = startRow - rangeStartRow + 1;
+        // Ensure valid range
+        if (startRow > endRow || startCol > endCol) {
+            return { sheetName, data: [], totalRows, returnedRows: 0, firstRow };
+        }
+        // Build 2D array (preserving types)
+        const data = [];
+        for (let r = startRow; r <= endRow; r++) {
+            const row = worksheet.getRow(r);
+            const rowData = [];
+            for (let c = startCol; c <= endCol; c++) {
+                const cell = row.getCell(c);
+                let value = null;
+                if (cell.value !== null && cell.value !== undefined) {
+                    if (typeof cell.value === 'object') {
+                        // Handle formula results, rich text, etc.
+                        if ('result' in cell.value) {
+                            value = cell.value.result ?? null;
+                        }
+                        else if ('richText' in cell.value) {
+                            value = cell.value.richText.map((rt) => rt.text).join('');
+                        }
+                        else if ('text' in cell.value) {
+                            value = cell.value.text;
+                        }
+                        else if (cell.value instanceof Date) {
+                            value = cell.value.toISOString();
+                        }
+                        else {
+                            value = String(cell.value);
+                        }
+                    }
+                    else {
+                        // Preserve native types (string, number, boolean)
+                        value = cell.value;
+                    }
+                }
+                rowData.push(value);
+            }
+            data.push(rowData);
+        }
+        return { sheetName, data, totalRows, returnedRows: data.length, firstRow };
+    }
+    writeDataToSheet(workbook, sheetName, data) {
+        // Remove existing sheet if it exists
+        const existing = workbook.getWorksheet(sheetName);
+        if (existing) {
+            workbook.removeWorksheet(existing.id);
+        }
+        const worksheet = workbook.addWorksheet(sheetName);
+        this.writeRowsStartingAt(worksheet, 1, data);
+    }
+    writeRowsStartingAt(worksheet, startRow, data) {
+        for (let r = 0; r < data.length; r++) {
+            const rowData = data[r];
+            if (!Array.isArray(rowData))
+                continue;
+            const row = worksheet.getRow(startRow + r);
+            for (let c = 0; c < rowData.length; c++) {
+                const value = rowData[c];
+                if (typeof value === 'string' && value.startsWith('=')) {
+                    row.getCell(c + 1).value = { formula: value.substring(1) };
+                }
+                else {
+                    row.getCell(c + 1).value = value;
+                }
+            }
+            row.commit();
+        }
+    }
+    parseRange(range) {
+        if (range.includes('!')) {
+            const idx = range.indexOf('!');
+            let sheetName = range.slice(0, idx);
+            const cellRange = range.slice(idx + 1);
+            // Strip Excel-native single quotes around sheet names with spaces:
+            // 'My Sheet'!A1 → My Sheet, A1
+            if (sheetName.length >= 2 && sheetName.startsWith("'") && sheetName.endsWith("'")) {
+                sheetName = sheetName.slice(1, -1).replace(/''/g, "'");
+            }
+            return [sheetName, cellRange];
+        }
+        return [range, null];
+    }
+    parseCellRange(range) {
+        // Parse A1 or A1:C10 format
+        const match = range.match(/^([A-Z]+)(\d+)(?::([A-Z]+)(\d+))?$/i);
+        if (!match) {
+            throw new Error(`Invalid cell range: "${range}". Expected forms: "A1", "A1:C10", or "SheetName!A1:C10" ` +
+                `(single-quote sheet names containing spaces: "'My Sheet'!A1:C10").`);
+        }
+        const startCol = this.columnToNumber(match[1]);
+        const startRow = parseInt(match[2], 10);
+        if (match[3] && match[4]) {
+            // Any two opposite corners name the range, as in Excel: A5:C2,
+            // C2:A5 and C5:A2 are all A2:C5
+            const endCol = this.columnToNumber(match[3]);
+            const endRow = parseInt(match[4], 10);
+            return {
+                startRow: Math.min(startRow, endRow),
+                startCol: Math.min(startCol, endCol),
+                endRow: Math.max(startRow, endRow),
+                endCol: Math.max(startCol, endCol)
+            };
+        }
+        return { startRow, startCol };
+    }
+    columnToNumber(col) {
+        // Column letters are case-insensitive, as in Excel: "b" is column B (2)
+        const letters = col.toUpperCase();
+        let result = 0;
+        for (let i = 0; i < letters.length; i++) {
+            result = result * 26 + letters.charCodeAt(i) - 64;
+        }
+        return result;
+    }
+}

package/dist/vendor/desktop-commander/dist/utils/files/factory.js

@@ -0,0 +1,168 @@
+/**
+ * Factory pattern for creating appropriate file handlers
+ * Routes file operations to the correct handler based on file type
+ *
+ * Each handler implements canHandle() which can be sync (extension-based)
+ * or async (content-based like BinaryFileHandler using isBinaryFile)
+ */
+import path from 'path';
+import { TextFileHandler } from './text.js';
+import { ImageFileHandler } from './image.js';
+import { BinaryFileHandler } from './binary.js';
+import { ExcelFileHandler, exceljsPackage } from './excel.js';
+import { PdfFileHandler } from './pdf.js';
+import { DocxFileHandler, pizzipPackage } from './docx.js';
+import { pdfLibPackage } from '../../tools/pdf/manipulations.js';
+import { pdf2mdPackage } from '../../tools/pdf/lib/pdf2md.js';
+import { unpdfPackage } from '../../tools/pdf/extract-images.js';
+import { mdToPdfPackage } from '../../tools/pdf/markdown.js';
+// Singleton instances of each handler
+let excelHandler = null;
+let imageHandler = null;
+let textHandler = null;
+let binaryHandler = null;
+let pdfHandler = null;
+let docxHandler = null;
+/**
+ * Initialize handlers (lazy initialization)
+ */
+function getExcelHandler() {
+    if (!excelHandler)
+        excelHandler = new ExcelFileHandler();
+    return excelHandler;
+}
+function getImageHandler() {
+    if (!imageHandler)
+        imageHandler = new ImageFileHandler();
+    return imageHandler;
+}
+function getTextHandler() {
+    if (!textHandler)
+        textHandler = new TextFileHandler();
+    return textHandler;
+}
+function getBinaryHandler() {
+    if (!binaryHandler)
+        binaryHandler = new BinaryFileHandler();
+    return binaryHandler;
+}
+function getPdfHandler() {
+    if (!pdfHandler)
+        pdfHandler = new PdfFileHandler();
+    return pdfHandler;
+}
+function getDocxHandler() {
+    if (!docxHandler)
+        docxHandler = new DocxFileHandler();
+    return docxHandler;
+}
+/**
+ * Get the appropriate file handler for a given file path
+ *
+ * Each handler's canHandle() determines if it can process the file.
+ * Extension-based handlers (Excel, Image) return sync boolean.
+ * BinaryFileHandler uses async isBinaryFile for content-based detection.
+ *
+ * Priority order:
+ * 1. DOCX files (extension based)
+ * 2. PDF files (extension based)
+ * 3. Excel files (xlsx, xls, xlsm) - extension based
+ * 4. Image files (png, jpg, gif, webp) - extension based
+ * 5. Binary files - content-based detection via isBinaryFile
+ * 6. Text files (default)
+ *
+ * @param filePath File path to get handler for
+ * @param options svgAsImage: an SVG goes to the image handler, for the file preview widget
+ * @returns FileHandler instance that can handle this file
+ */
+export async function getFileHandler(filePath, options) {
+    // Check DOCX first (extension-based, sync)
+    if (getDocxHandler().canHandle(filePath)) {
+        return getDocxHandler();
+    }
+    // Check PDF (extension-based, sync)
+    if (getPdfHandler().canHandle(filePath)) {
+        return getPdfHandler();
+    }
+    // Check Excel (extension-based, sync)
+    if (getExcelHandler().canHandle(filePath)) {
+        return getExcelHandler();
+    }
+    // Check Image (extension-based, sync - images are binary but handled specially)
+    if (getImageHandler().canHandle(filePath, options)) {
+        return getImageHandler();
+    }
+    // Check Binary (content-based, async via isBinaryFile)
+    if (await getBinaryHandler().canHandle(filePath)) {
+        return getBinaryHandler();
+    }
+    // Default to text handler
+    return getTextHandler();
+}
+/**
+ * Check if a file path is an Excel file
+ * Delegates to ExcelFileHandler.canHandle to avoid duplicating extension logic
+ * @param path File path
+ * @returns true if file is Excel format
+ */
+export function isExcelFile(path) {
+    return getExcelHandler().canHandle(path);
+}
+/**
+ * Check if a file path is an image file
+ * Delegates to ImageFileHandler.canHandle to avoid duplicating extension logic
+ * @param path File path
+ * @returns true if file is an image format
+ */
+export function isImageFile(path) {
+    return getImageHandler().canHandle(path);
+}
+/**
+ * Right after initialize (#777): the packages Excel, DOCX and PDF files need,
+ * loaded in the background one at a time, smaller first, so each pause of the
+ * main thread is one package.
+ */
+export function preloadFileSupport() {
+    void (async () => {
+        for (const pkg of [pizzipPackage, pdfLibPackage, pdf2mdPackage, unpdfPackage, exceljsPackage, mdToPdfPackage]) {
+            await pkg.preload();
+        }
+    })();
+}
+/** The packages a file needs for `action`, by the handlers' canHandle() (its name, no disk access) */
+function packagesFor(filePath, action, isPdf, isUrl) {
+    if (isPdf) {
+        // Editing a PDF can insert markdown pages, which are rendered
+        return action === 'read' ? [pdf2mdPackage, unpdfPackage] : action === 'write' ? [mdToPdfPackage] : [pdfLibPackage, mdToPdfPackage];
+    }
+    // A URL is fetched, not opened by a file handler: only a PDF one is parsed
+    if (isUrl)
+        return [];
+    if (getDocxHandler().canHandle(filePath))
+        return [pizzipPackage];
+    if (getExcelHandler().canHandle(filePath))
+        return [exceljsPackage];
+    return [];
+}
+/**
+ * The answer for a tool call that would `action` `filePath` while a package it
+ * needs is still loading, naming the file; undefined once loaded. A package
+ * not preloading yet (before initialize, or after a failure) starts here,
+ * after the call has answered. `isPdf` for a PDF whatever its name (write_pdf),
+ * `isUrl` for a URL read.
+ */
+export function stillLoadingError(filePath, action, { isPdf = getPdfHandler().canHandle(filePath), isUrl = false } = {}) {
+    const pending = packagesFor(filePath, action, isPdf, isUrl).find((pkg) => !pkg.loaded);
+    if (!pending)
+        return undefined;
+    const file = path.basename(filePath);
+    const { error, needsRestart, support } = pending;
+    if (!needsRestart)
+        void pending.preload();
+    if (!error) {
+        return `Can't ${action} ${file} yet: Desktop Commander is still loading its ${support} (it starts right after launch). Try again in a few seconds.`;
+    }
+    return needsRestart
+        ? `Can't ${action} ${file}: Desktop Commander couldn't load its ${support} (${error}). Restart Desktop Commander to load it again.`
+        : `Can't ${action} ${file}: Desktop Commander couldn't load its ${support} (${error}). It's loading it again; try again in a few seconds.`;
+}