@hcu-lab.me/mcp-device 1.0.0

package/dist/tools/edit.js

@@ -0,0 +1,435 @@
+/**
+ * Text file editing via search/replace with fuzzy matching support.
+ *
+ * TECHNICAL DEBT / ARCHITECTURAL NOTE:
+ * This file contains text editing logic that should ideally live in TextFileHandler.editRange()
+ * to be consistent with how Excel editing works (ExcelFileHandler.editRange()).
+ *
+ * Current inconsistency:
+ * - Excel: edit_block → ExcelFileHandler.editRange() ✓ uses file handler
+ * - Text:  edit_block → performSearchReplace() here → bypasses TextFileHandler
+ *
+ * Future refactor should:
+ * 1. Move performSearchReplace() + fuzzy logic into TextFileHandler.editRange()
+ * 2. Make this file a thin dispatch layer that routes to appropriate FileHandler
+ * 3. Unify the editRange() signature to handle both text search/replace and structured edits
+ */
+import { getDefaultEditorMetadata, writeFile, readFileInternal, validatePath } from './filesystem.js';
+import { runFuzzySearchInWorker, getSimilarityRatio } from './fuzzySearch.js';
+import { capture } from '../utils/capture.js';
+import { createErrorResponse } from '../error-handlers.js';
+import { EditBlockArgsSchema } from "./schemas.js";
+import path from 'path';
+import { detectLineEnding, normalizeLineEndings } from '../utils/lineEndingHandler.js';
+import { configManager } from '../config-manager.js';
+import { fuzzySearchLogger } from '../utils/fuzzySearchLogger.js';
+import { resolvePreviewFileType } from '../ui/file-preview/shared/preview-file-types.js';
+import { resolveAbsolutePath } from '../handlers/filesystem-handlers.js';
+/**
+ * Threshold for fuzzy matching - similarity must be at least this value to be considered
+ * (0-1 scale where 1 is perfect match and 0 is completely different)
+ */
+const FUZZY_THRESHOLD = 0.7;
+/**
+ * Extract character code data from diff
+ * @param expected The string that was searched for
+ * @param actual The string that was found
+ * @returns Character code statistics
+ */
+function getCharacterCodeData(expected, actual) {
+    // Find common prefix and suffix
+    let prefixLength = 0;
+    const minLength = Math.min(expected.length, actual.length);
+    // Determine common prefix length
+    while (prefixLength < minLength &&
+        expected[prefixLength] === actual[prefixLength]) {
+        prefixLength++;
+    }
+    // Determine common suffix length
+    let suffixLength = 0;
+    while (suffixLength < minLength - prefixLength &&
+        expected[expected.length - 1 - suffixLength] === actual[actual.length - 1 - suffixLength]) {
+        suffixLength++;
+    }
+    // Extract the different parts
+    const expectedDiff = expected.substring(prefixLength, expected.length - suffixLength);
+    const actualDiff = actual.substring(prefixLength, actual.length - suffixLength);
+    // Count unique character codes in the diff
+    const characterCodes = new Map();
+    const fullDiff = expectedDiff + actualDiff;
+    for (let i = 0; i < fullDiff.length; i++) {
+        const charCode = fullDiff.charCodeAt(i);
+        characterCodes.set(charCode, (characterCodes.get(charCode) || 0) + 1);
+    }
+    // Create character codes string report
+    const charCodeReport = [];
+    characterCodes.forEach((count, code) => {
+        // Include character representation for better readability
+        const char = String.fromCharCode(code);
+        // Make special characters more readable
+        const charDisplay = code < 32 || code > 126 ? `\\x${code.toString(16).padStart(2, '0')}` : char;
+        charCodeReport.push(`${code}:${count}[${charDisplay}]`);
+    });
+    // Sort by character code for consistency
+    charCodeReport.sort((a, b) => {
+        const codeA = parseInt(a.split(':')[0]);
+        const codeB = parseInt(b.split(':')[0]);
+        return codeA - codeB;
+    });
+    return {
+        report: charCodeReport.join(','),
+        uniqueCount: characterCodes.size,
+        diffLength: fullDiff.length
+    };
+}
+export async function performSearchReplace(filePath, block, expectedReplacements = 1, origin) {
+    // Get file extension for telemetry using path module
+    const fileExtension = path.extname(filePath).toLowerCase();
+    // Capture file extension and string sizes in telemetry without capturing the file path
+    capture('server_edit_block', {
+        fileExtension: fileExtension,
+        oldStringLength: block.search.length,
+        oldStringLines: block.search.split('\n').length,
+        newStringLength: block.replace.length,
+        newStringLines: block.replace.split('\n').length,
+        expectedReplacements: expectedReplacements
+    });
+    // Check for empty search string to prevent infinite loops
+    if (block.search === "") {
+        // Capture file extension in telemetry without capturing the file path
+        capture('server_edit_block_empty_search', { fileExtension: fileExtension, expectedReplacements });
+        return {
+            content: [{
+                    type: "text",
+                    text: "Empty search strings are not allowed. Please provide a non-empty string to search for."
+                }],
+        };
+    }
+    // Read file directly to preserve line endings - critical for edit operations
+    const validPath = await validatePath(filePath);
+    const content = await readFileInternal(validPath, 0, Number.MAX_SAFE_INTEGER);
+    // Make sure content is a string
+    if (typeof content !== 'string') {
+        capture('server_edit_block_content_not_string', { fileExtension: fileExtension, expectedReplacements });
+        throw new Error('Wrong content for file ' + filePath);
+    }
+    // Get the line limit from configuration
+    const config = await configManager.getConfig();
+    const MAX_LINES = config.fileWriteLineLimit ?? 50; // Default to 50 if not set
+    // Detect file's line ending style
+    const fileLineEnding = detectLineEnding(content);
+    // Normalize search string to match file's line endings
+    const normalizedSearch = normalizeLineEndings(block.search, fileLineEnding);
+    // First try exact match
+    let tempContent = content;
+    let count = 0;
+    let pos = tempContent.indexOf(normalizedSearch);
+    while (pos !== -1) {
+        count++;
+        pos = tempContent.indexOf(normalizedSearch, pos + 1);
+    }
+    // If exact match found and count matches expected replacements, proceed with exact replacement
+    if (count > 0 && count === expectedReplacements) {
+        // Replace all occurrences
+        let newContent = content;
+        // If we're only replacing one occurrence, replace it directly
+        if (expectedReplacements === 1) {
+            const searchIndex = newContent.indexOf(normalizedSearch);
+            newContent =
+                newContent.substring(0, searchIndex) +
+                    normalizeLineEndings(block.replace, fileLineEnding) +
+                    newContent.substring(searchIndex + normalizedSearch.length);
+        }
+        else {
+            // Replace all occurrences using split and join for multiple replacements
+            newContent = newContent.split(normalizedSearch).join(normalizeLineEndings(block.replace, fileLineEnding));
+        }
+        // Check if search or replace text has too many lines
+        const searchLines = block.search.split('\n').length;
+        const replaceLines = block.replace.split('\n').length;
+        const maxLines = Math.max(searchLines, replaceLines);
+        let warningMessage = "";
+        if (maxLines > MAX_LINES) {
+            const problemText = searchLines > replaceLines ? 'search text' : 'replacement text';
+            warningMessage = `\n\nWARNING: The ${problemText} has ${maxLines} lines (maximum: ${MAX_LINES}).
+            
+RECOMMENDATION: For large search/replace operations, consider breaking them into smaller chunks with fewer lines.`;
+        }
+        await writeFile(filePath, newContent);
+        capture('server_edit_block_exact_success', { fileExtension: fileExtension, expectedReplacements, hasWarning: warningMessage !== "" });
+        const resolvedEditPath = resolveAbsolutePath(filePath);
+        // Show a partial preview centered on the edited area
+        const newLines = newContent.split('\n');
+        const totalLines = newLines.length;
+        const changePos = content.indexOf(normalizedSearch);
+        const changeStartLine = changePos >= 0 ? newContent.substring(0, changePos).split('\n').length - 1 : 0;
+        const changeLineCount = block.replace.split('\n').length;
+        const contextLines = 10;
+        const previewStart = Math.max(0, changeStartLine - contextLines);
+        const previewEnd = Math.min(totalLines, changeStartLine + changeLineCount + contextLines);
+        const previewContent = newLines.slice(previewStart, previewEnd).join('\n');
+        const previewLineCount = previewEnd - previewStart;
+        const remaining = totalLines - previewEnd;
+        const statusLine = `[Reading ${previewLineCount} lines from ${previewStart === 0 ? 'start' : `line ${previewStart}`} (total: ${totalLines} lines, ${remaining} remaining)]\n\n`;
+        return {
+            content: [{
+                    type: "text",
+                    text: `${statusLine}${previewContent}`
+                }],
+            // structuredContent only travels on widget-initiated calls: it is the
+            // widget's save-success signal (assertSuccessfulEditBlockResult) and
+            // metadata source. LLM-facing responses don't need it — nothing there
+            // consumes it, and the widget re-reads by path instead.
+            ...(origin === 'ui' ? {
+                structuredContent: {
+                    fileName: path.basename(resolvedEditPath),
+                    filePath: resolvedEditPath,
+                    fileType: resolvePreviewFileType(resolvedEditPath),
+                    ...await getDefaultEditorMetadata(resolvedEditPath),
+                },
+            } : {}),
+        };
+    }
+    // If exact match found but count doesn't match expected, inform the user
+    if (count > 0 && count !== expectedReplacements) {
+        capture('server_edit_block_unexpected_count', { fileExtension: fileExtension, expectedReplacements, expectedReplacementsCount: count });
+        return {
+            content: [{
+                    type: "text",
+                    text: `Expected ${expectedReplacements} occurrences but found ${count} in ${filePath}. ` +
+                        `Double check and make sure you understand all occurencies and if you want to replace all ${count} occurrences, set expected_replacements to ${count}. ` +
+                        `If there are many occurrancies and you want to change some of them and keep the rest. Do it one by one, by adding more lines around each occurrence.` +
+                        `If you want to replace a specific occurrence, make your search string more unique by adding more lines around search string.`
+                }],
+        };
+    }
+    // If exact match not found, try fuzzy search
+    if (count === 0) {
+        // Track fuzzy search time
+        const startTime = performance.now();
+        // Perform fuzzy search in a worker thread so the main event loop stays
+        // responsive to pings and parallel tool calls during the scan
+        const fuzzyResult = await runFuzzySearchInWorker(content, block.search);
+        const similarity = getSimilarityRatio(block.search, fuzzyResult.value);
+        // Calculate execution time in milliseconds
+        const executionTime = performance.now() - startTime;
+        // Generate diff and gather character code data
+        const diff = highlightDifferences(block.search, fuzzyResult.value);
+        // Count character codes in diff
+        const characterCodeData = getCharacterCodeData(block.search, fuzzyResult.value);
+        // Create comprehensive log entry
+        const logEntry = {
+            timestamp: new Date(),
+            searchText: block.search,
+            foundText: fuzzyResult.value,
+            similarity: similarity,
+            executionTime: executionTime,
+            exactMatchCount: count,
+            expectedReplacements: expectedReplacements,
+            fuzzyThreshold: FUZZY_THRESHOLD,
+            belowThreshold: similarity < FUZZY_THRESHOLD,
+            diff: diff,
+            searchLength: block.search.length,
+            foundLength: fuzzyResult.value.length,
+            fileExtension: fileExtension,
+            characterCodes: characterCodeData.report,
+            uniqueCharacterCount: characterCodeData.uniqueCount,
+            diffLength: characterCodeData.diffLength
+        };
+        // Log to file
+        await fuzzySearchLogger.log(logEntry);
+        // Combine all fuzzy search data for single capture
+        const fuzzySearchData = {
+            similarity: similarity,
+            execution_time_ms: executionTime,
+            search_length: block.search.length,
+            file_size: content.length,
+            threshold: FUZZY_THRESHOLD,
+            found_text_length: fuzzyResult.value.length,
+            character_codes: characterCodeData.report,
+            unique_character_count: characterCodeData.uniqueCount,
+            total_diff_length: characterCodeData.diffLength
+        };
+        // Check if the fuzzy match is "close enough"
+        if (similarity >= FUZZY_THRESHOLD) {
+            // Capture the fuzzy search event with all data
+            capture('server_fuzzy_search_performed', fuzzySearchData);
+            // If we allow fuzzy matches, we would make the replacement here
+            // For now, we'll return a detailed message about the fuzzy match
+            return {
+                content: [{
+                        type: "text",
+                        text: `Exact match not found, but found a similar text with ${Math.round(similarity * 100)}% similarity (found in ${executionTime.toFixed(2)}ms):\n\n` +
+                            `Differences:\n${diff}\n\n` +
+                            `To replace this text, use the exact text found in the file.\n\n` +
+                            `Log entry saved for analysis. Use the following command to check the log:\n` +
+                            `Check log: ${await fuzzySearchLogger.getLogPath()}`
+                    }], // TODO
+            };
+        }
+        else {
+            // If the fuzzy match isn't close enough
+            // Still capture the fuzzy search event with all data
+            capture('server_fuzzy_search_performed', {
+                ...fuzzySearchData,
+                below_threshold: true
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Search content not found in ${filePath}. The closest match was "${fuzzyResult.value}" ` +
+                            `with only ${Math.round(similarity * 100)}% similarity, which is below the ${Math.round(FUZZY_THRESHOLD * 100)}% threshold. ` +
+                            `(Fuzzy search completed in ${executionTime.toFixed(2)}ms)\n\n` +
+                            `Log entry saved for analysis. Use the following command to check the log:\n` +
+                            `Check log: ${await fuzzySearchLogger.getLogPath()}`
+                    }],
+            };
+        }
+    }
+    throw new Error("Unexpected error during search and replace operation.");
+}
+/**
+ * Generates a character-level diff using standard {-removed-}{+added+} format
+ * @param expected The string that was searched for
+ * @param actual The string that was found
+ * @returns A formatted string showing character-level differences
+ */
+function highlightDifferences(expected, actual) {
+    // Implementation of a simplified character-level diff
+    // Find common prefix and suffix
+    let prefixLength = 0;
+    const minLength = Math.min(expected.length, actual.length);
+    // Determine common prefix length
+    while (prefixLength < minLength &&
+        expected[prefixLength] === actual[prefixLength]) {
+        prefixLength++;
+    }
+    // Determine common suffix length
+    let suffixLength = 0;
+    while (suffixLength < minLength - prefixLength &&
+        expected[expected.length - 1 - suffixLength] === actual[actual.length - 1 - suffixLength]) {
+        suffixLength++;
+    }
+    // Extract the common and different parts
+    const commonPrefix = expected.substring(0, prefixLength);
+    const commonSuffix = expected.substring(expected.length - suffixLength);
+    const expectedDiff = expected.substring(prefixLength, expected.length - suffixLength);
+    const actualDiff = actual.substring(prefixLength, actual.length - suffixLength);
+    // Format the output as a character-level diff
+    return `${commonPrefix}{-${expectedDiff}-}{+${actualDiff}+}${commonSuffix}`;
+}
+/**
+ * Handle edit_block command
+ *
+ * 1. Text files: String replacement (old_string/new_string)
+ *    - Uses fuzzy matching for resilience
+ *    - Handles expected_replacements parameter
+ *
+ * 2. Structured files (Excel): Range rewrite (range + content)
+ *    - Bulk updates to cell ranges (e.g., "Sheet1!A1:C10")
+ *    - Whole sheet replacement (e.g., "Sheet1")
+ *    - More powerful and simpler than surgical location-based edits
+ *    - Supports chunking for large datasets (e.g., 1000 rows at a time)
+
+ */
+export async function handleEditBlock(args) {
+    const parsed = EditBlockArgsSchema.parse(args);
+    // Note: Check for truthy range to handle empty strings from AI clients that send all optional params
+    const hasRange = parsed.range !== undefined && parsed.range !== '';
+    const hasContent = parsed.content !== undefined && parsed.content !== '';
+    // Validate path and resolve handler once — used by both dispatch paths below
+    let validatedPath;
+    let handler;
+    try {
+        validatedPath = await validatePath(parsed.file_path);
+        const { getFileHandler } = await import('../utils/files/factory.js');
+        handler = await getFileHandler(validatedPath);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createErrorResponse(errorMessage);
+    }
+    const hasEditRange = 'editRange' in handler && typeof handler.editRange === 'function';
+    // Path 1: Range rewrite (Excel, etc.) — range + content
+    if (hasRange && hasContent) {
+        // Parse content if it's a JSON string (AI often sends arrays as JSON strings)
+        let content = parsed.content;
+        if (typeof content === 'string') {
+            try {
+                content = JSON.parse(content);
+            }
+            catch {
+                // Leave as-is if not valid JSON - let handler decide
+            }
+        }
+        if (hasEditRange) {
+            try {
+                // parsed.range is guaranteed non-empty string by hasRange check above
+                await handler.editRange(validatedPath, parsed.range, content, parsed.options);
+                const resolvedRangePath = resolveAbsolutePath(parsed.file_path);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Successfully updated range ${parsed.range} in ${parsed.file_path}`
+                        }],
+                    ...(parsed.origin === 'ui' ? {
+                        structuredContent: {
+                            fileName: path.basename(resolvedRangePath),
+                            filePath: resolvedRangePath,
+                            fileType: resolvePreviewFileType(resolvedRangePath),
+                            ...await getDefaultEditorMetadata(resolvedRangePath),
+                        },
+                    } : {}),
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return createErrorResponse(errorMessage);
+            }
+        }
+        return createErrorResponse(`Range-based editing not supported for ${parsed.file_path}. For text files, use old_string and new_string parameters instead. If your client requires range/content parameters, set them to empty strings ("").`);
+    }
+    // Path 2: Text replacement — old_string + new_string
+    if (parsed.old_string === undefined || parsed.new_string === undefined) {
+        return createErrorResponse(`Text replacement requires both old_string and new_string parameters`);
+    }
+    // If the handler implements editRange it owns text-replacement for its file type
+    // (e.g. DocxFileHandler does find/replace on pretty-printed XML rather than raw bytes).
+    // Plain text files fall through to performSearchReplace.
+    if (hasEditRange) {
+        try {
+            const result = await handler.editRange(validatedPath, '', {
+                old_string: parsed.old_string,
+                new_string: parsed.new_string,
+                expected_replacements: parsed.expected_replacements,
+            });
+            if (result.success) {
+                const resolvedEditRangePath = resolveAbsolutePath(parsed.file_path);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Successfully applied ${result.editsApplied} edit(s) to ${parsed.file_path}`
+                        }],
+                    ...(parsed.origin === 'ui' ? {
+                        structuredContent: {
+                            fileName: path.basename(resolvedEditRangePath),
+                            filePath: resolvedEditRangePath,
+                            fileType: resolvePreviewFileType(resolvedEditRangePath),
+                            ...await getDefaultEditorMetadata(resolvedEditRangePath),
+                        },
+                    } : {}),
+                };
+            }
+            const errorMsg = result.errors?.map(e => e.error).join('; ') || 'Unknown error';
+            return createErrorResponse(errorMsg);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return createErrorResponse(errorMessage);
+        }
+    }
+    return performSearchReplace(parsed.file_path, {
+        search: parsed.old_string,
+        replace: parsed.new_string
+    }, parsed.expected_replacements, parsed.origin);
+}

package/dist/tools/feedback.d.ts

@@ -0,0 +1,8 @@
+import { ServerResult } from '../types.js';
+interface FeedbackParams {
+}
+/**
+ * Open feedback form in browser with optional pre-filled data
+ */
+export declare function giveFeedbackToDesktopCommander(params?: FeedbackParams): Promise<ServerResult>;
+export {};

package/dist/tools/feedback.js

@@ -0,0 +1,132 @@
+import { usageTracker } from '../utils/usageTracker.js';
+import { capture } from '../utils/capture.js';
+import { configManager } from '../config-manager.js';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as os from 'os';
+const execAsync = promisify(exec);
+/**
+ * Open feedback form in browser with optional pre-filled data
+ */
+export async function giveFeedbackToDesktopCommander(params = {}) {
+    try {
+        // Get usage stats for context
+        const stats = await usageTracker.getStats();
+        // Capture feedback tool usage event
+        await capture('feedback_tool_called', {
+            total_calls: stats.totalToolCalls,
+            successful_calls: stats.successfulCalls,
+            failed_calls: stats.failedCalls,
+            days_since_first_use: Math.floor((Date.now() - stats.firstUsed) / (1000 * 60 * 60 * 24)),
+            total_sessions: stats.totalSessions,
+            platform: os.platform(),
+        });
+        // Build Tally.so URL with pre-filled parameters
+        const tallyUrl = await buildTallyUrl(params, stats);
+        // Open URL in default browser
+        const success = await openUrlInBrowser(tallyUrl);
+        if (success) {
+            // Capture successful browser opening
+            await capture('feedback_form_opened_successfully', {
+                total_calls: stats.totalToolCalls,
+                platform: os.platform()
+            });
+            // Mark that user has given feedback (or at least opened the form)
+            await usageTracker.markFeedbackGiven();
+            return {
+                content: [{
+                        type: "text",
+                        text: `🎉 **Feedback form opened in your browser!**\n\n` +
+                            `Thank you for taking the time to share your experience with MCP Device. ` +
+                            `Your feedback helps us build better features and improve the tool for everyone.\n\n` +
+                            `The form has been pre-filled with the information you provided. ` +
+                            `You can modify or add any additional details before submitting.\n\n` +
+                            `**Form URL**: ${tallyUrl.length > 100 ? tallyUrl.substring(0, 100) + '...' : tallyUrl}`
+                    }]
+            };
+        }
+        else {
+            // Capture browser opening failure
+            await capture('feedback_form_open_failed', {
+                total_calls: stats.totalToolCalls,
+                platform: os.platform(),
+                error_type: 'browser_open_failed'
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `⚠️ **Couldn't open browser automatically**\n\n` +
+                            `Please copy and paste this URL into your browser to access the feedback form:\n\n` +
+                            `${tallyUrl}\n\n` +
+                            `The form has been pre-filled with your information. Thank you for your feedback!`
+                    }]
+            };
+        }
+    }
+    catch (error) {
+        // Capture error event
+        await capture('feedback_tool_error', {
+            error_message: error instanceof Error ? error.message : String(error),
+            error_type: error instanceof Error ? error.constructor.name : 'unknown'
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: `❌ **Error opening feedback form**: ${error instanceof Error ? error.message : String(error)}\n\n` +
+                        `You can still access our feedback form directly at: https://tally.so/r/mKqoKg\n\n` +
+                        `We appreciate your willingness to provide feedback!`
+                }],
+            isError: true
+        };
+    }
+}
+/**
+ * Build Tally.so URL with pre-filled parameters
+ */
+async function buildTallyUrl(params, stats) {
+    const baseUrl = 'https://tally.so/r/mKqoKg';
+    const urlParams = new URLSearchParams();
+    // Only auto-filled hidden fields remain
+    urlParams.set('tool_call_count', stats.totalToolCalls.toString());
+    // Calculate days using
+    const daysUsing = Math.floor((Date.now() - stats.firstUsed) / (1000 * 60 * 60 * 24));
+    urlParams.set('days_using', daysUsing.toString());
+    // Add platform info
+    urlParams.set('platform', os.platform());
+    // Add client_id from analytics config
+    try {
+        const clientId = await configManager.getValue('clientId') || 'unknown';
+        urlParams.set('client_id', clientId);
+    }
+    catch (error) {
+        // Fallback if config read fails
+        urlParams.set('client_id', 'unknown');
+    }
+    return `${baseUrl}?${urlParams.toString()}`;
+}
+/**
+ * Open URL in default browser (cross-platform)
+ */
+async function openUrlInBrowser(url) {
+    try {
+        const platform = os.platform();
+        let command;
+        switch (platform) {
+            case 'darwin': // macOS
+                command = `open "${url}"`;
+                break;
+            case 'win32': // Windows
+                command = `start "" "${url}"`;
+                break;
+            default: // Linux and others
+                command = `xdg-open "${url}"`;
+                break;
+        }
+        await execAsync(command);
+        return true;
+    }
+    catch (error) {
+        console.error('Failed to open browser:', error);
+        return false;
+    }
+}

package/dist/tools/filesystem.d.ts

@@ -0,0 +1,79 @@
+import type { ReadOptions, FileResult, PdfPageItem } from '../utils/files/base.js';
+import { PdfOperations, PdfMetadata } from './pdf/index.js';
+export declare const READ_OPERATION_TIMEOUT_MS: number;
+/**
+ * Validates a path to ensure it can be accessed or created.
+ * For existing paths, returns the real path (resolving symlinks).
+ * For non-existent paths, validates parent directories to ensure they exist.
+ *
+ * @param requestedPath The path to validate
+ * @returns Promise<string> The validated path
+ * @throws Error if the path or its parent directories don't exist or if the path is not allowed
+ */
+export declare function validatePath(requestedPath: string): Promise<string>;
+export type { FileResult } from '../utils/files/base.js';
+type PdfPayload = {
+    metadata: PdfMetadata;
+    pages: PdfPageItem[];
+};
+type FileResultPayloads = PdfPayload;
+/**
+ * Read file content from a URL
+ * @param url URL to fetch content from
+ * @returns File content or file result with metadata
+ */
+export declare function readFileFromUrl(url: string): Promise<FileResult>;
+/**
+ * Read file content from the local filesystem
+ * @param filePath Path to the file
+ * @param options Read options (offset, length, sheet, range)
+ * @returns File content or file result with metadata
+ */
+export declare function readFileFromDisk(filePath: string, options?: ReadOptions): Promise<FileResult>;
+/**
+ * Read a file from either the local filesystem or a URL
+ * @param filePath Path to the file or URL
+ * @param options Read options (isUrl, offset, length, sheet, range)
+ * @returns File content or file result with metadata
+ */
+export declare function readFile(filePath: string, options?: ReadOptions): Promise<FileResult>;
+/**
+ * Read file content without status messages for internal operations
+ * This function preserves exact file content including original line endings,
+ * which is essential for edit operations that need to maintain file formatting.
+ * @param filePath Path to the file
+ * @param offset Starting line number to read from (default: 0)
+ * @param length Maximum number of lines to read (default: from config or 1000)
+ * @returns File content without status headers, with preserved line endings
+ */
+export declare function readFileInternal(filePath: string, offset?: number, length?: number): Promise<string>;
+export declare function writeFile(filePath: string, content: string, mode?: 'rewrite' | 'append'): Promise<void>;
+export interface MultiFileResult {
+    path: string;
+    content?: string;
+    mimeType?: string;
+    isImage?: boolean;
+    error?: string;
+    isPdf?: boolean;
+    payload?: FileResultPayloads;
+}
+export declare function readMultipleFiles(paths: string[]): Promise<MultiFileResult[]>;
+export declare function createDirectory(dirPath: string): Promise<void>;
+export declare function listDirectory(dirPath: string, depth?: number): Promise<string[]>;
+export declare function moveFile(sourcePath: string, destinationPath: string): Promise<void>;
+export declare function searchFiles(rootPath: string, pattern: string): Promise<string[]>;
+export declare function getFileInfo(filePath: string): Promise<Record<string, any>>;
+/**
+ * Write content to a PDF file.
+ * Can create a new PDF from Markdown string, or modify an existing PDF using operations.
+ *
+ * @param filePath Path to the output PDF file
+ * @param content Markdown string (for creation) or array of operations (for modification)
+ * @param options Options for PDF generation or modification. For modification, can include `sourcePdf`.
+ */
+export declare function writePdf(filePath: string, content: string | PdfOperations[], outputPath?: string, options?: any): Promise<void>;
+type DefaultEditorMetadata = {
+    defaultEditorName?: string;
+    defaultEditorPath?: string;
+};
+export declare function getDefaultEditorMetadata(filePath: string): Promise<DefaultEditorMetadata>;