@hcu-lab.me/mcp-device 1.0.0

package/dist/utils/files/text.js

@@ -0,0 +1,370 @@
+/**
+ * Text file handler
+ * Handles reading, writing, and editing text files
+ *
+ * Binary detection is handled at the factory level (factory.ts) using isBinaryFile.
+ * This handler only receives files that have been confirmed as text.
+ *
+ * TECHNICAL DEBT:
+ * This handler is missing editRange() - text search/replace logic currently lives in
+ * src/tools/edit.ts (performSearchReplace function) instead of here.
+ *
+ * For architectural consistency with ExcelFileHandler.editRange(), the fuzzy
+ * search/replace logic should be moved here. See comment in src/tools/edit.ts.
+ */
+import fs from "fs/promises";
+import { createReadStream } from 'fs';
+import { createInterface } from 'readline';
+// TODO: Centralize these constants with filesystem.ts to avoid silent drift
+// These duplicate concepts from filesystem.ts and should be moved to a shared
+// constants module (e.g., src/utils/files/constants.ts) during reorganization
+const FILE_SIZE_LIMITS = {
+    LARGE_FILE_THRESHOLD: 10 * 1024 * 1024, // 10MB
+    LINE_COUNT_LIMIT: 10 * 1024 * 1024, // 10MB for line counting
+};
+const READ_PERFORMANCE_THRESHOLDS = {
+    SMALL_READ_THRESHOLD: 100, // For very small reads
+    DEEP_OFFSET_THRESHOLD: 1000, // For byte estimation
+    SAMPLE_SIZE: 10000, // Sample size for estimation
+    CHUNK_SIZE: 8192, // 8KB chunks for reverse reading
+};
+/**
+ * Text file handler implementation
+ * Binary detection is done at the factory level - this handler assumes file is text
+ */
+export class TextFileHandler {
+    canHandle(_path) {
+        // Text handler accepts all files that pass the factory's binary check
+        // The factory routes binary files to BinaryFileHandler before reaching here
+        return true;
+    }
+    async read(filePath, options) {
+        const offset = options?.offset ?? 0;
+        const length = options?.length ?? 1000; // Default from config
+        const includeStatusMessage = options?.includeStatusMessage ?? true;
+        // Binary detection is done at factory level - just read as text
+        return this.readFileWithSmartPositioning(filePath, offset, length, 'text/plain', includeStatusMessage, options?.signal);
+    }
+    async write(path, content, mode = 'rewrite') {
+        if (mode === 'append') {
+            await fs.appendFile(path, content);
+        }
+        else {
+            await fs.writeFile(path, content);
+        }
+    }
+    async getInfo(path) {
+        const stats = await fs.stat(path);
+        const info = {
+            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: 'text',
+            metadata: {}
+        };
+        // For text files that aren't too large, count lines
+        if (stats.isFile() && stats.size < FILE_SIZE_LIMITS.LINE_COUNT_LIMIT) {
+            try {
+                const content = await fs.readFile(path, 'utf8');
+                const lineCount = TextFileHandler.countLines(content);
+                info.metadata.lineCount = lineCount;
+            }
+            catch (error) {
+                // If reading fails, skip line count
+            }
+        }
+        return info;
+    }
+    // ========================================================================
+    // Private Helper Methods (extracted from filesystem.ts)
+    // ========================================================================
+    /**
+     * Count lines in text content
+     * Made static and public for use by other modules (e.g., writeFile telemetry in filesystem.ts)
+     */
+    static countLines(content) {
+        if (content === '')
+            return 0;
+        // A file with N lines has N-1 newline characters.
+        // If the file ends with a trailing newline, don't count the empty string after it.
+        const lines = content.split('\n');
+        if (lines[lines.length - 1] === '') {
+            return lines.length - 1;
+        }
+        return lines.length;
+    }
+    /**
+     * Get file line count (for files under size limit)
+     */
+    async getFileLineCount(filePath, signal) {
+        try {
+            const stats = await fs.stat(filePath);
+            if (stats.size < FILE_SIZE_LIMITS.LINE_COUNT_LIMIT) {
+                const content = await fs.readFile(filePath, { encoding: 'utf8', signal });
+                return TextFileHandler.countLines(content);
+            }
+        }
+        catch (error) {
+            // If we can't read the file, return undefined
+        }
+        return undefined;
+    }
+    /**
+     * Generate enhanced status message
+     */
+    generateEnhancedStatusMessage(readLines, offset, totalLines, isNegativeOffset = false) {
+        if (isNegativeOffset) {
+            if (totalLines !== undefined) {
+                return `[Reading last ${readLines} lines (total: ${totalLines} lines)]`;
+            }
+            else {
+                return `[Reading last ${readLines} lines]`;
+            }
+        }
+        else {
+            if (totalLines !== undefined) {
+                const endLine = offset + readLines;
+                const remainingLines = Math.max(0, totalLines - endLine);
+                if (offset === 0) {
+                    return `[Reading ${readLines} lines from start (total: ${totalLines} lines, ${remainingLines} remaining)]`;
+                }
+                else {
+                    return `[Reading ${readLines} lines from line ${offset} (total: ${totalLines} lines, ${remainingLines} remaining)]`;
+                }
+            }
+            else {
+                if (offset === 0) {
+                    return `[Reading ${readLines} lines from start]`;
+                }
+                else {
+                    return `[Reading ${readLines} lines from line ${offset}]`;
+                }
+            }
+        }
+    }
+    /**
+     * Split text into lines while preserving line endings
+     * Made static and public for use by other modules (e.g., readFileInternal in filesystem.ts)
+     */
+    static splitLinesPreservingEndings(content) {
+        if (!content)
+            return [''];
+        const lines = [];
+        let currentLine = '';
+        for (let i = 0; i < content.length; i++) {
+            const char = content[i];
+            currentLine += char;
+            if (char === '\n') {
+                lines.push(currentLine);
+                currentLine = '';
+            }
+            else if (char === '\r') {
+                if (i + 1 < content.length && content[i + 1] === '\n') {
+                    currentLine += content[i + 1];
+                    i++;
+                }
+                lines.push(currentLine);
+                currentLine = '';
+            }
+        }
+        if (currentLine) {
+            lines.push(currentLine);
+        }
+        return lines;
+    }
+    /**
+     * Read file with smart positioning for optimal performance
+     */
+    async readFileWithSmartPositioning(filePath, offset, length, mimeType, includeStatusMessage = true, signal) {
+        const stats = await fs.stat(filePath);
+        const fileSize = stats.size;
+        const totalLines = await this.getFileLineCount(filePath, signal);
+        // For negative offsets (tail behavior), use reverse reading
+        if (offset < 0) {
+            const requestedLines = Math.abs(offset);
+            if (fileSize > FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD &&
+                requestedLines <= READ_PERFORMANCE_THRESHOLDS.SMALL_READ_THRESHOLD) {
+                return await this.readLastNLinesReverse(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
+            }
+            else {
+                return await this.readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage, totalLines, signal);
+            }
+        }
+        // For positive offsets
+        else {
+            if (fileSize < FILE_SIZE_LIMITS.LARGE_FILE_THRESHOLD || offset === 0) {
+                return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
+            }
+            else {
+                if (offset > READ_PERFORMANCE_THRESHOLDS.DEEP_OFFSET_THRESHOLD) {
+                    return await this.readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
+                }
+                else {
+                    return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, totalLines, signal);
+                }
+            }
+        }
+    }
+    /**
+     * Read last N lines efficiently by reading file backwards
+     */
+    async readLastNLinesReverse(filePath, n, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
+        const fd = await fs.open(filePath, 'r');
+        try {
+            const stats = await fd.stat();
+            const fileSize = stats.size;
+            let position = fileSize;
+            let lines = [];
+            let partialLine = '';
+            while (position > 0 && lines.length < n) {
+                if (signal?.aborted) {
+                    const err = new Error('Read aborted');
+                    err.code = 'ABORT_ERR';
+                    throw err;
+                }
+                const readSize = Math.min(READ_PERFORMANCE_THRESHOLDS.CHUNK_SIZE, position);
+                position -= readSize;
+                const buffer = Buffer.alloc(readSize);
+                await fd.read(buffer, 0, readSize, position);
+                const chunk = buffer.toString('utf-8');
+                const text = chunk + partialLine;
+                const chunkLines = text.split('\n');
+                partialLine = chunkLines.shift() || '';
+                lines = chunkLines.concat(lines);
+            }
+            if (position === 0 && partialLine) {
+                lines.unshift(partialLine);
+            }
+            const result = lines.slice(-n);
+            const content = includeStatusMessage
+                ? `${this.generateEnhancedStatusMessage(result.length, -n, fileTotalLines, true)}\n\n${result.join('\n')}`
+                : result.join('\n');
+            return { content, mimeType, metadata: {} };
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    /**
+     * Read from end using readline with circular buffer
+     */
+    async readFromEndWithReadline(filePath, requestedLines, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
+        const rl = createInterface({
+            input: createReadStream(filePath, { signal }),
+            crlfDelay: Infinity
+        });
+        const buffer = new Array(requestedLines);
+        let bufferIndex = 0;
+        let totalLines = 0;
+        for await (const line of rl) {
+            buffer[bufferIndex] = line;
+            bufferIndex = (bufferIndex + 1) % requestedLines;
+            totalLines++;
+        }
+        rl.close();
+        let result;
+        if (totalLines >= requestedLines) {
+            result = [
+                ...buffer.slice(bufferIndex),
+                ...buffer.slice(0, bufferIndex)
+            ].filter(line => line !== undefined);
+        }
+        else {
+            result = buffer.slice(0, totalLines);
+        }
+        const content = includeStatusMessage
+            ? `${this.generateEnhancedStatusMessage(result.length, -requestedLines, fileTotalLines, true)}\n\n${result.join('\n')}`
+            : result.join('\n');
+        return { content, mimeType, metadata: {} };
+    }
+    /**
+     * Read from start/middle using readline
+     */
+    async readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
+        const rl = createInterface({
+            input: createReadStream(filePath, { signal }),
+            crlfDelay: Infinity
+        });
+        const result = [];
+        let lineNumber = 0;
+        for await (const line of rl) {
+            if (lineNumber >= offset && result.length < length) {
+                result.push(line);
+            }
+            if (result.length >= length)
+                break;
+            lineNumber++;
+        }
+        rl.close();
+        if (includeStatusMessage) {
+            const statusMessage = this.generateEnhancedStatusMessage(result.length, offset, fileTotalLines, false);
+            const content = `${statusMessage}\n\n${result.join('\n')}`;
+            return { content, mimeType, metadata: {} };
+        }
+        else {
+            const content = result.join('\n');
+            return { content, mimeType, metadata: {} };
+        }
+    }
+    /**
+     * Read from estimated byte position for very large files
+     */
+    async readFromEstimatedPosition(filePath, offset, length, mimeType, includeStatusMessage = true, fileTotalLines, signal) {
+        // First, do a quick scan to estimate lines per byte
+        const rl = createInterface({
+            input: createReadStream(filePath, { signal }),
+            crlfDelay: Infinity
+        });
+        let sampleLines = 0;
+        let bytesRead = 0;
+        for await (const line of rl) {
+            bytesRead += Buffer.byteLength(line, 'utf-8') + 1;
+            sampleLines++;
+            if (bytesRead >= READ_PERFORMANCE_THRESHOLDS.SAMPLE_SIZE)
+                break;
+        }
+        rl.close();
+        if (sampleLines === 0) {
+            return await this.readFromStartWithReadline(filePath, offset, length, mimeType, includeStatusMessage, fileTotalLines, signal);
+        }
+        // Estimate position
+        const avgLineLength = bytesRead / sampleLines;
+        const estimatedBytePosition = Math.floor(offset * avgLineLength);
+        const fd = await fs.open(filePath, 'r');
+        try {
+            const stats = await fd.stat();
+            const startPosition = Math.min(estimatedBytePosition, stats.size);
+            const stream = createReadStream(filePath, { start: startPosition, signal });
+            const rl2 = createInterface({
+                input: stream,
+                crlfDelay: Infinity
+            });
+            const result = [];
+            let firstLineSkipped = false;
+            for await (const line of rl2) {
+                if (!firstLineSkipped && startPosition > 0) {
+                    firstLineSkipped = true;
+                    continue;
+                }
+                if (result.length < length) {
+                    result.push(line);
+                }
+                else {
+                    break;
+                }
+            }
+            rl2.close();
+            const content = includeStatusMessage
+                ? `${this.generateEnhancedStatusMessage(result.length, offset, fileTotalLines, false)}\n\n${result.join('\n')}`
+                : result.join('\n');
+            return { content, mimeType, metadata: {} };
+        }
+        finally {
+            await fd.close();
+        }
+    }
+}

package/dist/utils/fuzzySearchLogger.d.ts

@@ -0,0 +1,30 @@
+export interface FuzzySearchLogEntry {
+    timestamp: Date;
+    searchText: string;
+    foundText: string;
+    similarity: number;
+    executionTime: number;
+    exactMatchCount: number;
+    expectedReplacements: number;
+    fuzzyThreshold: number;
+    belowThreshold: boolean;
+    diff: string;
+    searchLength: number;
+    foundLength: number;
+    fileExtension: string;
+    characterCodes: string;
+    uniqueCharacterCount: number;
+    diffLength: number;
+}
+declare class FuzzySearchLogger {
+    private logPath;
+    private initialized;
+    constructor();
+    private ensureLogFile;
+    log(entry: FuzzySearchLogEntry): Promise<void>;
+    getLogPath(): Promise<string>;
+    getRecentLogs(count?: number): Promise<string[]>;
+    clearLog(): Promise<void>;
+}
+export declare const fuzzySearchLogger: FuzzySearchLogger;
+export {};

package/dist/utils/fuzzySearchLogger.js

@@ -0,0 +1,126 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG_DIR } from '../config.js';
+class FuzzySearchLogger {
+    constructor() {
+        this.initialized = false;
+        // Keep logs under the canonical MCP Device state root.
+        const logDir = path.join(CONFIG_DIR, 'logs');
+        this.logPath = path.join(logDir, 'fuzzy-search.log');
+    }
+    async ensureLogFile() {
+        if (this.initialized)
+            return;
+        try {
+            // Create log directory if it doesn't exist
+            const logDir = path.dirname(this.logPath);
+            await fs.mkdir(logDir, { recursive: true });
+            // Check if log file exists, create with headers if not
+            try {
+                await fs.access(this.logPath);
+            }
+            catch {
+                // File doesn't exist, create with headers
+                const headers = [
+                    'timestamp',
+                    'searchText',
+                    'foundText',
+                    'similarity',
+                    'executionTime',
+                    'exactMatchCount',
+                    'expectedReplacements',
+                    'fuzzyThreshold',
+                    'belowThreshold',
+                    'diff',
+                    'searchLength',
+                    'foundLength',
+                    'fileExtension',
+                    'characterCodes',
+                    'uniqueCharacterCount',
+                    'diffLength'
+                ].join('\t');
+                await fs.writeFile(this.logPath, headers + '\n');
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            console.error('Failed to initialize fuzzy search log file:', error);
+            throw error;
+        }
+    }
+    async log(entry) {
+        try {
+            await this.ensureLogFile();
+            // Convert entry to tab-separated string
+            const logLine = [
+                entry.timestamp.toISOString(),
+                entry.searchText.replace(/\n/g, '\\n').replace(/\t/g, '\\t'),
+                entry.foundText.replace(/\n/g, '\\n').replace(/\t/g, '\\t'),
+                entry.similarity.toString(),
+                entry.executionTime.toString(),
+                entry.exactMatchCount.toString(),
+                entry.expectedReplacements.toString(),
+                entry.fuzzyThreshold.toString(),
+                entry.belowThreshold.toString(),
+                entry.diff.replace(/\n/g, '\\n').replace(/\t/g, '\\t'),
+                entry.searchLength.toString(),
+                entry.foundLength.toString(),
+                entry.fileExtension,
+                entry.characterCodes,
+                entry.uniqueCharacterCount.toString(),
+                entry.diffLength.toString()
+            ].join('\t');
+            await fs.appendFile(this.logPath, logLine + '\n');
+        }
+        catch (error) {
+            console.error('Failed to write to fuzzy search log:', error);
+        }
+    }
+    async getLogPath() {
+        await this.ensureLogFile();
+        return this.logPath;
+    }
+    async getRecentLogs(count = 10) {
+        try {
+            await this.ensureLogFile();
+            const content = await fs.readFile(this.logPath, 'utf-8');
+            const lines = content.split('\n').filter(line => line.trim());
+            // Return last N lines (excluding header)
+            return lines.slice(-count - 1, -1);
+        }
+        catch (error) {
+            console.error('Failed to read fuzzy search logs:', error);
+            return [];
+        }
+    }
+    async clearLog() {
+        try {
+            // Recreate with just headers
+            const headers = [
+                'timestamp',
+                'searchText',
+                'foundText',
+                'similarity',
+                'executionTime',
+                'exactMatchCount',
+                'expectedReplacements',
+                'fuzzyThreshold',
+                'belowThreshold',
+                'diff',
+                'searchLength',
+                'foundLength',
+                'fileExtension',
+                'characterCodes',
+                'uniqueCharacterCount',
+                'diffLength'
+            ].join('\t');
+            await fs.writeFile(this.logPath, headers + '\n');
+            console.log('Fuzzy search log cleared');
+        }
+        catch (error) {
+            console.error('Failed to clear fuzzy search log:', error);
+        }
+    }
+}
+// Singleton instance
+export const fuzzySearchLogger = new FuzzySearchLogger();

package/dist/utils/lineEndingHandler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Line ending types
+ */
+export type LineEndingStyle = '\r\n' | '\n' | '\r';
+/**
+ * Detect the line ending style used in a file - Optimized version
+ * This algorithm uses early termination for maximum performance
+ */
+export declare function detectLineEnding(content: string): LineEndingStyle;
+/**
+ * Normalize line endings to match the target style
+ */
+export declare function normalizeLineEndings(text: string, targetLineEnding: LineEndingStyle): string;
+/**
+ * Analyze line ending usage in content
+ */
+export declare function analyzeLineEndings(content: string): {
+    style: LineEndingStyle;
+    count: number;
+    hasMixed: boolean;
+};

package/dist/utils/lineEndingHandler.js

@@ -0,0 +1,77 @@
+/**
+ * Detect the line ending style used in a file - Optimized version
+ * This algorithm uses early termination for maximum performance
+ */
+export function detectLineEnding(content) {
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === '\r') {
+            if (i + 1 < content.length && content[i + 1] === '\n') {
+                return '\r\n';
+            }
+            return '\r';
+        }
+        if (content[i] === '\n') {
+            return '\n';
+        }
+    }
+    // Default to system line ending if no line endings found
+    return process.platform === 'win32' ? '\r\n' : '\n';
+}
+/**
+ * Normalize line endings to match the target style
+ */
+export function normalizeLineEndings(text, targetLineEnding) {
+    // First normalize to LF
+    let normalized = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    // Then convert to target
+    if (targetLineEnding === '\r\n') {
+        return normalized.replace(/\n/g, '\r\n');
+    }
+    else if (targetLineEnding === '\r') {
+        return normalized.replace(/\n/g, '\r');
+    }
+    return normalized;
+}
+/**
+ * Analyze line ending usage in content
+ */
+export function analyzeLineEndings(content) {
+    let crlfCount = 0;
+    let lfCount = 0;
+    let crCount = 0;
+    // Count line endings
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === '\r') {
+            if (i + 1 < content.length && content[i + 1] === '\n') {
+                crlfCount++;
+                i++; // Skip the LF
+            }
+            else {
+                crCount++;
+            }
+        }
+        else if (content[i] === '\n') {
+            lfCount++;
+        }
+    }
+    // Determine predominant style
+    const total = crlfCount + lfCount + crCount;
+    let style;
+    if (crlfCount > lfCount && crlfCount > crCount) {
+        style = '\r\n';
+    }
+    else if (lfCount > crCount) {
+        style = '\n';
+    }
+    else {
+        style = '\r';
+    }
+    // Check for mixed line endings
+    const usedStyles = [crlfCount > 0, lfCount > 0, crCount > 0].filter(Boolean).length;
+    const hasMixed = usedStyles > 1;
+    return {
+        style,
+        count: total,
+        hasMixed
+    };
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Centralized logging utility for MCP Device
+ * Ensures all logging goes through proper channels based on initialization state
+ */
+import type { FilteredStdioServerTransport } from '../custom-stdio.js';
+declare global {
+    var mcpTransport: FilteredStdioServerTransport | undefined;
+}
+export type LogLevel = 'emergency' | 'alert' | 'critical' | 'error' | 'warning' | 'notice' | 'info' | 'debug';
+/**
+ * Log a message using the appropriate method based on MCP initialization state
+ */
+export declare function log(level: LogLevel, message: string, data?: any): void;
+/**
+ * Convenience functions for different log levels
+ */
+export declare const logger: {
+    emergency: (message: string, data?: any) => void;
+    alert: (message: string, data?: any) => void;
+    critical: (message: string, data?: any) => void;
+    error: (message: string, data?: any) => void;
+    warning: (message: string, data?: any) => void;
+    notice: (message: string, data?: any) => void;
+    info: (message: string, data?: any) => void;
+    debug: (message: string, data?: any) => void;
+};
+/**
+ * Log to stderr during early initialization (before MCP is ready)
+ * Use this for critical startup messages that must be visible
+ * NOTE: This should also be JSON-RPC format
+ */
+export declare function logToStderr(level: LogLevel, message: string): void;