DesktopCommanderMCP Line Ending Handler System for Cross-Platform Compatibility

DesktopCommanderMCP implements a dedicated line ending handler system in src/utils/lineEndingHandler.ts that detects, normalizes, and analyzes line endings to ensure files remain consistent across Windows, macOS, and Linux environments.

The DesktopCommanderMCP repository provides a robust solution for handling the differences between Windows (\r\n), Unix/macOS (\n), and legacy Mac (\r) line endings. When editing or searching files, the line ending handler system for cross-platform compatibility ensures that operations respect the original file's formatting while preventing mixed-ending corruption. This system is implemented as a set of pure utility functions that integrate seamlessly with the tool's file editing workflows.

Three-Stage Line Ending Processing

The handler operates through three distinct stages implemented in src/utils/lineEndingHandler.ts:

Detection with detectLineEnding

The detectLineEnding(content) function scans raw file text to identify the predominant line ending style. It returns the first line ending encountered ('\r\n', '\n', or '\r') with an early-exit loop for O(N) performance. If the file contains no line breaks, the function falls back to the host OS default via process.platform.

Normalization with normalizeLineEndings

The normalizeLineEndings(text, targetLineEnding) function ensures that search strings, replacement text, and generated content match the target file's convention. It performs a two-pass conversion: first collapsing all line breaks to LF (\n), then re-applying the desired style (\r\n or \r). This guarantees consistent line endings throughout editing operations.

Analysis with analyzeLineEndings

The analyzeLineEndings(content) function provides diagnostic capabilities by counting occurrences of each line ending style. It returns the predominant style, total count, and a boolean flag indicating whether mixed line endings are present. This is essential for warning users when files contain inconsistent formatting.

Integration in Editing Workflows

All editing operations in DesktopCommanderMCP invoke the line ending handler to preserve file integrity. In src/tools/edit.ts, the system detects the file's line ending style and normalizes user-supplied search strings before performing replacements. This approach prevents "file changed" notifications when the same repository is accessed across different operating systems.

Practical Implementation Examples

Here's how to use the line ending handler system in your own implementations:

import {
  detectLineEnding,
  normalizeLineEndings,
  analyzeLineEndings,
} from './utils/lineEndingHandler.js';

// Detect the file's native line ending style
const raw = await readFile('example.txt');
const fileEnding = detectLineEnding(raw);  // Returns '\r\n' on Windows files

// Normalize user input to match the file's style
const userSearch = 'foo\r\nbar';
const searchFor = normalizeLineEndings(userSearch, fileEnding);

// Analyze for mixed line endings
const {style, count, hasMixed} = analyzeLineEndings(raw);
if (hasMixed) {
  console.warn(`Mixed endings detected: ${count} total, predominant: ${style}`);
}

Summary

• The line ending handler system resides in src/utils/lineEndingHandler.ts and provides three core functions: detectLineEnding, normalizeLineEndings, and analyzeLineEndings.
• Detection identifies the file's line ending style or falls back to the OS default, ensuring O(N) performance through early-exit scanning.
• Normalization converts any input text to match the target file's line ending convention via a two-pass LF intermediate step.
• Analysis counts line ending occurrences and flags mixed styles for diagnostic purposes.
• Integration in src/tools/edit.ts demonstrates real-world usage where search strings are normalized before replacement to maintain cross-platform consistency.

Frequently Asked Questions

How does DesktopCommanderMCP handle files with no line endings?

When detectLineEnding encounters a file without any line breaks, it returns the host operating system's default line ending based on process.platform. This ensures that any new content added to the file uses the appropriate convention for the current environment.

Can the line ending handler convert between different line ending styles?

Yes. The normalizeLineEndings function accepts a targetLineEnding parameter and converts any input text to use that specific style. It first normalizes all line breaks to LF (\n), then replaces them with the target style, effectively converting between Windows (\r\n), Unix (\n), and legacy Mac (\r) formats.

Where is the line ending handler used in the codebase?

The primary consumer is src/tools/edit.ts, where the handler detects line endings and normalizes search strings before performing replacements. Additional usage appears in src/tools/filesystem.ts for reading files without stripping line endings, ensuring the entire editing pipeline respects the original file formatting.

Does the system warn about mixed line endings?

Yes. The analyzeLineEndings function explicitly checks for mixed line endings by counting occurrences of each style (\r\n, \n, \r). It returns a hasMixed boolean flag and statistical data, allowing the application to warn users when files contain inconsistent line ending conventions that might cause issues in version control or cross-platform collaboration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}