@wonderwhy-er/desktop-commander 0.2.22 → 0.2.24

package/dist/tools/schemas.d.ts

@@ -30,15 +30,21 @@ export declare const StartProcessArgsSchema: z.ZodObject<{
 export declare const ReadProcessOutputArgsSchema: z.ZodObject<{
     pid: z.ZodNumber;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    length: z.ZodOptional<z.ZodNumber>;
     verbose_timing: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     pid: number;
+    length?: number | undefined;
     timeout_ms?: number | undefined;
     verbose_timing?: boolean | undefined;
+    offset?: number | undefined;
 }, {
     pid: number;
+    length?: number | undefined;
     timeout_ms?: number | undefined;
     verbose_timing?: boolean | undefined;
+    offset?: number | undefined;
 }>;
 export declare const ForceTerminateArgsSchema: z.ZodObject<{
     pid: z.ZodNumber;
@@ -60,16 +66,25 @@ export declare const ReadFileArgsSchema: z.ZodObject<{
     isUrl: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     length: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sheet: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     length: number;
     path: string;
-    isUrl: boolean;
     offset: number;
+    isUrl: boolean;
+    options?: Record<string, any> | undefined;
+    sheet?: string | undefined;
+    range?: string | undefined;
 }, {
     path: string;
     length?: number | undefined;
-    isUrl?: boolean | undefined;
+    options?: Record<string, any> | undefined;
     offset?: number | undefined;
+    isUrl?: boolean | undefined;
+    sheet?: string | undefined;
+    range?: string | undefined;
 }>;
 export declare const ReadMultipleFilesArgsSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString, "many">;
@@ -91,6 +106,124 @@ export declare const WriteFileArgsSchema: z.ZodObject<{
     content: string;
     mode?: "rewrite" | "append" | undefined;
 }>;
+export declare const PdfInsertOperationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"insert">;
+    pageIndex: z.ZodNumber;
+    markdown: z.ZodOptional<z.ZodString>;
+    sourcePdfPath: z.ZodOptional<z.ZodString>;
+    pdfOptions: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    type: "insert";
+    pageIndex: number;
+    markdown?: string | undefined;
+    sourcePdfPath?: string | undefined;
+    pdfOptions?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    type: "insert";
+    pageIndex: number;
+    markdown?: string | undefined;
+    sourcePdfPath?: string | undefined;
+    pdfOptions?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}>;
+export declare const PdfDeleteOperationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"delete">;
+    pageIndexes: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "delete";
+    pageIndexes: number[];
+}, {
+    type: "delete";
+    pageIndexes: number[];
+}>;
+export declare const PdfOperationSchema: z.ZodUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"insert">;
+    pageIndex: z.ZodNumber;
+    markdown: z.ZodOptional<z.ZodString>;
+    sourcePdfPath: z.ZodOptional<z.ZodString>;
+    pdfOptions: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    type: "insert";
+    pageIndex: number;
+    markdown?: string | undefined;
+    sourcePdfPath?: string | undefined;
+    pdfOptions?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    type: "insert";
+    pageIndex: number;
+    markdown?: string | undefined;
+    sourcePdfPath?: string | undefined;
+    pdfOptions?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"delete">;
+    pageIndexes: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "delete";
+    pageIndexes: number[];
+}, {
+    type: "delete";
+    pageIndexes: number[];
+}>]>;
+export declare const WritePdfArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"insert">;
+        pageIndex: z.ZodNumber;
+        markdown: z.ZodOptional<z.ZodString>;
+        sourcePdfPath: z.ZodOptional<z.ZodString>;
+        pdfOptions: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "insert";
+        pageIndex: number;
+        markdown?: string | undefined;
+        sourcePdfPath?: string | undefined;
+        pdfOptions?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }, {
+        type: "insert";
+        pageIndex: number;
+        markdown?: string | undefined;
+        sourcePdfPath?: string | undefined;
+        pdfOptions?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"delete">;
+        pageIndexes: z.ZodArray<z.ZodNumber, "many">;
+    }, "strip", z.ZodTypeAny, {
+        type: "delete";
+        pageIndexes: number[];
+    }, {
+        type: "delete";
+        pageIndexes: number[];
+    }>]>, "many">]>, string | ({
+        type: "insert";
+        pageIndex: number;
+        markdown?: string | undefined;
+        sourcePdfPath?: string | undefined;
+        pdfOptions?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | {
+        type: "delete";
+        pageIndexes: number[];
+    })[], unknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    content: string | ({
+        type: "insert";
+        pageIndex: number;
+        markdown?: string | undefined;
+        sourcePdfPath?: string | undefined;
+        pdfOptions?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    } | {
+        type: "delete";
+        pageIndexes: number[];
+    })[];
+    options?: z.objectOutputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    outputPath?: string | undefined;
+}, {
+    path: string;
+    options?: z.objectInputType<{}, z.ZodTypeAny, "passthrough"> | undefined;
+    content?: unknown;
+    outputPath?: string | undefined;
+}>;
 export declare const CreateDirectoryArgsSchema: z.ZodObject<{
     path: z.ZodString;
 }, "strip", z.ZodTypeAny, {
@@ -125,20 +258,45 @@ export declare const GetFileInfoArgsSchema: z.ZodObject<{
 }, {
     path: string;
 }>;
-export declare const EditBlockArgsSchema: z.ZodObject<{
+export declare const EditBlockArgsSchema: z.ZodEffects<z.ZodObject<{
     file_path: z.ZodString;
-    old_string: z.ZodString;
-    new_string: z.ZodString;
+    old_string: z.ZodOptional<z.ZodString>;
+    new_string: z.ZodOptional<z.ZodString>;
     expected_replacements: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    range: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodAny>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     file_path: string;
-    old_string: string;
-    new_string: string;
     expected_replacements: number;
+    options?: Record<string, any> | undefined;
+    range?: string | undefined;
+    content?: any;
+    old_string?: string | undefined;
+    new_string?: string | undefined;
+}, {
+    file_path: string;
+    options?: Record<string, any> | undefined;
+    range?: string | undefined;
+    content?: any;
+    old_string?: string | undefined;
+    new_string?: string | undefined;
+    expected_replacements?: number | undefined;
+}>, {
+    file_path: string;
+    expected_replacements: number;
+    options?: Record<string, any> | undefined;
+    range?: string | undefined;
+    content?: any;
+    old_string?: string | undefined;
+    new_string?: string | undefined;
 }, {
     file_path: string;
-    old_string: string;
-    new_string: string;
+    options?: Record<string, any> | undefined;
+    range?: string | undefined;
+    content?: any;
+    old_string?: string | undefined;
+    new_string?: string | undefined;
     expected_replacements?: number | undefined;
 }>;
 export declare const InteractWithProcessArgsSchema: z.ZodObject<{
@@ -223,15 +381,12 @@ export declare const ListSearchesArgsSchema: z.ZodObject<{}, "strip", z.ZodTypeA
 export declare const GetPromptsArgsSchema: z.ZodObject<{
     action: z.ZodEnum<["get_prompt"]>;
     promptId: z.ZodString;
-    anonymous_user_use_case: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     action: "get_prompt";
     promptId: string;
-    anonymous_user_use_case?: string | undefined;
 }, {
     action: "get_prompt";
     promptId: string;
-    anonymous_user_use_case?: string | undefined;
 }>;
 export declare const GetRecentToolCallsArgsSchema: z.ZodObject<{
     maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;

package/dist/tools/schemas.js

@@ -23,6 +23,8 @@ export const StartProcessArgsSchema = z.object({
 export const ReadProcessOutputArgsSchema = z.object({
     pid: z.number(),
     timeout_ms: z.number().optional(),
+    offset: z.number().optional(), // Line offset: 0=from last read, positive=absolute, negative=tail
+    length: z.number().optional(), // Max lines to return (default from config.fileReadLineLimit)
     verbose_timing: z.boolean().optional(),
 });
 export const ForceTerminateArgsSchema = z.object({
@@ -38,6 +40,9 @@ export const ReadFileArgsSchema = z.object({
     isUrl: z.boolean().optional().default(false),
     offset: z.number().optional().default(0),
     length: z.number().optional().default(1000),
+    sheet: z.string().optional(), // String only for MCP client compatibility (Cursor doesn't support union types in JSON Schema)
+    range: z.string().optional(),
+    options: z.record(z.any()).optional()
 });
 export const ReadMultipleFilesArgsSchema = z.object({
     paths: z.array(z.string()),
@@ -47,6 +52,39 @@ export const WriteFileArgsSchema = z.object({
     content: z.string(),
     mode: z.enum(['rewrite', 'append']).default('rewrite'),
 });
+// PDF modification schemas - exported for reuse
+export const PdfInsertOperationSchema = z.object({
+    type: z.literal('insert'),
+    pageIndex: z.number(),
+    markdown: z.string().optional(),
+    sourcePdfPath: z.string().optional(),
+    pdfOptions: z.object({}).passthrough().optional(),
+});
+export const PdfDeleteOperationSchema = z.object({
+    type: z.literal('delete'),
+    pageIndexes: z.array(z.number()),
+});
+export const PdfOperationSchema = z.union([PdfInsertOperationSchema, PdfDeleteOperationSchema]);
+export const WritePdfArgsSchema = z.object({
+    path: z.string(),
+    // Preprocess content to handle JSON strings that should be parsed as arrays
+    content: z.preprocess((val) => {
+        // If it's a string that looks like JSON array, parse it
+        if (typeof val === 'string' && val.trim().startsWith('[')) {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                // If parsing fails, return as-is (might be markdown content)
+                return val;
+            }
+        }
+        // Otherwise return as-is
+        return val;
+    }, z.union([z.string(), z.array(PdfOperationSchema)])),
+    outputPath: z.string().optional(),
+    options: z.object({}).passthrough().optional(), // Allow passing options to md-to-pdf
+});
 export const CreateDirectoryArgsSchema = z.object({
     path: z.string(),
 });
@@ -61,13 +99,23 @@ export const MoveFileArgsSchema = z.object({
 export const GetFileInfoArgsSchema = z.object({
     path: z.string(),
 });
-// Edit tools schema
+// Edit tools schema - SIMPLIFIED from three modes to two
+// Previously supported: text replacement, location-based edits (edits array), and range rewrites
+// Now supports only: text replacement and range rewrites
+// Removed 'edits' array parameter - location-based surgical edits were complex and unnecessary
+// Range rewrites are more powerful and cover all structured file editing needs
 export const EditBlockArgsSchema = z.object({
     file_path: z.string(),
-    old_string: z.string(),
-    new_string: z.string(),
+    // Text file string replacement
+    old_string: z.string().optional(),
+    new_string: z.string().optional(),
     expected_replacements: z.number().optional().default(1),
-});
+    // Structured file range rewrite (Excel, etc.)
+    range: z.string().optional(),
+    content: z.any().optional(),
+    options: z.record(z.any()).optional()
+}).refine(data => (data.old_string !== undefined && data.new_string !== undefined) ||
+    (data.range !== undefined && data.content !== undefined), { message: "Must provide either (old_string + new_string) or (range + content)" });
 // Send input to process schema
 export const InteractWithProcessArgsSchema = z.object({
     pid: z.number(),
@@ -114,7 +162,8 @@ export const ListSearchesArgsSchema = z.object({});
 export const GetPromptsArgsSchema = z.object({
     action: z.enum(['get_prompt']),
     promptId: z.string(),
-    anonymous_user_use_case: z.string().optional(),
+    // Disabled to check if it makes sense or should be removed or changed
+    // anonymous_user_use_case: z.string().optional(),
 });
 // Tool history schema
 export const GetRecentToolCallsArgsSchema = z.object({

package/dist/types.d.ts

@@ -13,7 +13,8 @@ export interface ProcessInfo {
 export interface TerminalSession {
     pid: number;
     process: ChildProcess;
-    lastOutput: string;
+    outputLines: string[];
+    lastReadIndex: number;
     isBlocked: boolean;
     startTime: Date;
 }

package/dist/utils/feature-flags.js

@@ -32,6 +32,9 @@ class FeatureFlagManager {
                     logger.debug('Periodic flag fetch failed:', err.message);
                 });
             }, this.cacheMaxAge);
+            // Allow process to exit even if interval is pending
+            // This is critical for proper cleanup when MCP client disconnects
+            this.refreshInterval.unref();
             logger.info(`Feature flags initialized (refresh every ${this.cacheMaxAge / 1000}s)`);
         }
         catch (error) {
@@ -89,7 +92,7 @@ class FeatureFlagManager {
      */
     async fetchFlags() {
         try {
-            logger.debug('Fetching feature flags from:', this.flagUrl);
+            // Don't log here - runs async and can interfere with MCP clients
             const controller = new AbortController();
             const timeout = setTimeout(() => controller.abort(), 5000);
             const response = await fetch(this.flagUrl, {
@@ -107,9 +110,9 @@ class FeatureFlagManager {
             if (config.flags) {
                 this.flags = config.flags;
                 this.lastFetch = Date.now();
-                // Save to cache
+                // Save to cache (silently - don't log during async operations
+                // as it can interfere with MCP clients that close quickly)
                 await this.saveToCache(config);
-                logger.info(`Feature flags updated: ${Object.keys(this.flags).length} flags`);
             }
         }
         catch (error) {
@@ -127,7 +130,7 @@ class FeatureFlagManager {
                 await fs.mkdir(configDir, { recursive: true });
             }
             await fs.writeFile(this.cachePath, JSON.stringify(config, null, 2), 'utf8');
-            logger.debug('Saved feature flags to cache');
+            // Don't log here - this runs async and can cause issues with MCP clients
         }
         catch (error) {
             logger.warning('Failed to save feature flags to cache:', error);

package/dist/utils/files/base.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Base interfaces and types for file handling system
+ * All file handlers implement the FileHandler interface
+ */
+/**
+ * Base interface that all file handlers must implement
+ */
+export interface FileHandler {
+    /**
+     * Read file content
+     * @param path Validated file path
+     * @param options Read options (offset, length, sheet, etc.)
+     * @returns File result with content and metadata
+     */
+    read(path: string, options?: ReadOptions): Promise<FileResult>;
+    /**
+     * Write file (complete rewrite or append)
+     * @param path Validated file path
+     * @param content Content to write
+     * @param mode Write mode: 'rewrite' (default) or 'append'
+     */
+    write(path: string, content: any, mode?: 'rewrite' | 'append'): Promise<void>;
+    /**
+     * Edit a specific range (bulk rewrite)
+     * PRIMARY METHOD for structured file editing (Excel, etc.)
+     * Simpler and more powerful than location-based edits
+     * Supports:
+     * - Cell ranges: "Sheet1!A1:C10" with 2D array content
+     * - Whole sheets: "Sheet1" to replace entire sheet
+     * - Chunking: Update 1000 rows at a time for large files
+     *
+     * Currently implemented by: ExcelFileHandler
+     * TECHNICAL DEBT: TextFileHandler should also implement this for search/replace
+     * (logic currently in src/tools/edit.ts - see comments there)
+     *
+     * @param path Validated file path
+     * @param range Range identifier (e.g., "Sheet1!A1:C10" or "Sheet1")
+     * @param content New content for the range (2D array for Excel)
+     * @param options Additional format-specific options
+     * @returns Result with success status
+     */
+    editRange?(path: string, range: string, content: any, options?: Record<string, any>): Promise<EditResult>;
+    /**
+     * Get file metadata
+     * @param path Validated file path
+     * @returns File information including type-specific metadata
+     */
+    getInfo(path: string): Promise<FileInfo>;
+    /**
+     * Check if this handler can handle the given file
+     * @param path File path
+     * @returns true if this handler supports this file type (can be async for content-based checks)
+     */
+    canHandle(path: string): boolean | Promise<boolean>;
+}
+/**
+ * Options for reading files
+ */
+export interface ReadOptions {
+    /** Whether the path is a URL */
+    isUrl?: boolean;
+    /** Starting line/row number (for text/excel) */
+    offset?: number;
+    /** Maximum number of lines/rows to read */
+    length?: number;
+    /** Excel-specific: Sheet name or index */
+    sheet?: string | number;
+    /** Excel-specific: Cell range (e.g., "A1:C10") */
+    range?: string;
+    /** Whether to include status messages (default: true) */
+    includeStatusMessage?: boolean;
+}
+/**
+ * Result from reading a file
+ */
+export interface FileResult {
+    /** File content (string for text/csv, Buffer for binary, base64 string for images) */
+    content: string | Buffer;
+    /** MIME type of the content */
+    mimeType: string;
+    /** Type-specific metadata */
+    metadata?: FileMetadata;
+}
+/**
+ * File-type specific metadata
+ */
+export interface FileMetadata {
+    /** For images */
+    isImage?: boolean;
+    /** For binary files */
+    isBinary?: boolean;
+    /** For Excel files */
+    isExcelFile?: boolean;
+    sheets?: ExcelSheet[];
+    fileSize?: number;
+    isLargeFile?: boolean;
+    /** For text files */
+    lineCount?: number;
+    /** For PDF files */
+    isPdf?: boolean;
+    author?: string;
+    title?: string;
+    totalPages?: number;
+    pages?: PdfPageItem[];
+    /** Error information if operation failed */
+    error?: boolean;
+    errorMessage?: string;
+}
+/**
+ * PDF page content item
+ */
+export interface PdfPageItem {
+    pageNumber: number;
+    text: string;
+    images: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+}
+/**
+ * Excel sheet metadata
+ */
+export interface ExcelSheet {
+    /** Sheet name */
+    name: string;
+    /** Number of rows in sheet */
+    rowCount: number;
+    /** Number of columns in sheet */
+    colCount: number;
+}
+/**
+ * Result from edit operation (used by editRange)
+ */
+export interface EditResult {
+    /** Whether all edits succeeded */
+    success: boolean;
+    /** Number of edits successfully applied */
+    editsApplied: number;
+    /** Errors that occurred during editing */
+    errors?: Array<{
+        location: string;
+        error: string;
+    }>;
+}
+/**
+ * File information and metadata
+ */
+export interface FileInfo {
+    /** File size in bytes */
+    size: number;
+    /** Creation time */
+    created: Date;
+    /** Last modification time */
+    modified: Date;
+    /** Last access time */
+    accessed: Date;
+    /** Is this a directory */
+    isDirectory: boolean;
+    /** Is this a regular file */
+    isFile: boolean;
+    /** File permissions (octal string) */
+    permissions: string;
+    /** File type classification */
+    fileType: 'text' | 'excel' | 'image' | 'binary';
+    /** Type-specific metadata */
+    metadata?: FileMetadata;
+}

package/dist/utils/files/base.js

@@ -0,0 +1,5 @@
+/**
+ * Base interfaces and types for file handling system
+ * All file handlers implement the FileHandler interface
+ */
+export {};

package/dist/utils/files/binary.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Binary file handler
+ * Handles binary files that aren't supported by other handlers (Excel, Image)
+ * Uses isBinaryFile for content-based detection
+ * Returns instructions to use start_process with appropriate tools
+ */
+import { FileHandler, ReadOptions, FileResult, FileInfo } from './base.js';
+/**
+ * Binary file handler implementation
+ * Uses content-based detection via isBinaryFile
+ */
+export declare class BinaryFileHandler implements FileHandler {
+    canHandle(filePath: string): Promise<boolean>;
+    read(filePath: string, options?: ReadOptions): Promise<FileResult>;
+    write(path: string, content: any): Promise<void>;
+    getInfo(path: string): Promise<FileInfo>;
+    /**
+     * Generate instructions for handling binary files
+     */
+    private getBinaryInstructions;
+}

package/dist/utils/files/binary.js

@@ -0,0 +1,65 @@
+/**
+ * Binary file handler
+ * Handles binary files that aren't supported by other handlers (Excel, Image)
+ * Uses isBinaryFile for content-based detection
+ * Returns instructions to use start_process with appropriate tools
+ */
+import fs from "fs/promises";
+import path from "path";
+import { isBinaryFile } from 'isbinaryfile';
+/**
+ * Binary file handler implementation
+ * Uses content-based detection via isBinaryFile
+ */
+export class BinaryFileHandler {
+    async canHandle(filePath) {
+        // Content-based binary detection using isBinaryFile
+        try {
+            return await isBinaryFile(filePath);
+        }
+        catch (error) {
+            // If we can't check (file doesn't exist, etc.), don't handle it
+            return false;
+        }
+    }
+    async read(filePath, options) {
+        const instructions = this.getBinaryInstructions(filePath);
+        return {
+            content: instructions,
+            mimeType: 'text/plain',
+            metadata: {
+                isBinary: true
+            }
+        };
+    }
+    async write(path, content) {
+        throw new Error('Cannot write binary files directly. Use start_process with appropriate tools (Python, Node.js libraries, command-line utilities).');
+    }
+    async getInfo(path) {
+        const stats = await fs.stat(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: 'binary',
+            metadata: {
+                isBinary: true
+            }
+        };
+    }
+    /**
+     * Generate instructions for handling binary files
+     */
+    getBinaryInstructions(filePath) {
+        const fileName = path.basename(filePath);
+        return `Cannot read binary file as text: ${fileName}
+
+Use start_process + interact_with_process to analyze binary files with appropriate tools (Node.js or Python libraries, command-line utilities, etc.).
+
+The read_file tool only handles text files, images, and Excel files.`;
+    }
+}

package/dist/utils/files/excel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Excel file handler using ExcelJS
+ * Handles reading, writing, and editing Excel files (.xlsx, .xls, .xlsm)
+ */
+import { FileHandler, ReadOptions, FileResult, EditResult, FileInfo } from './base.js';
+/**
+ * Excel file handler implementation using ExcelJS
+ * Supports: .xlsx, .xls, .xlsm files
+ */
+export declare class ExcelFileHandler implements FileHandler {
+    canHandle(path: string): boolean;
+    read(path: string, options?: ReadOptions): Promise<FileResult>;
+    write(path: string, content: any, mode?: 'rewrite' | 'append'): Promise<void>;
+    editRange(path: string, range: string, content: any, options?: Record<string, any>): Promise<EditResult>;
+    getInfo(path: string): Promise<FileInfo>;
+    private checkFileSize;
+    private extractMetadata;
+    private worksheetToArray;
+    private writeDataToSheet;
+    private writeRowsStartingAt;
+    private parseRange;
+    private parseCellRange;
+    private columnToNumber;
+}