@sofianedjerbi/knowledge-tree-mcp/docs/backend/troubleshooting/windows-path-separator-cross-platform-edge.json

MCP server for hierarchical project knowledge management

{
  "title": "Windows Path Separator Cross-Platform Edge Cases",
  "priority": "EDGE-CASE",
  "problem": "Windows systems use backslashes for path separators while Unix systems use forward slashes, causing edge cases in path handling and JSON file storage that can break cross-platform compatibility.",
  "solution": "## Specific Windows Edge Cases\n\n### JSON Path Storage\n```typescript\n// EDGE CASE: Windows paths in JSON get double-escaped\nconst entry = {\n  path: \"C:\\\\Users\\\\Name\\\\docs\\\\entry.json\", // Becomes C:\\\\\\\\Users...\n  related_to: [{\n    path: \"..\\\\..\\\\other\\\\entry.json\" // Breaks on Unix\n  }]\n};\n\n// WORKAROUND: Always normalize paths before JSON storage\nimport { posix } from 'path';\n\nfunction normalizePathForStorage(path: string): string {\n  return path.split(require('path').sep).join(posix.sep);\n}\n```\n\n### Case-Insensitive Filesystem Conflicts\n```typescript\n// EDGE CASE: Windows filesystem is case-insensitive\n// These create the same file on Windows but different files on Unix\nawait writeFile('Entry.json', content1);\nawait writeFile('entry.json', content2); // Overwrites on Windows!\n\n// WORKAROUND: Force lowercase for all generated paths\nfunction generateSafeFilename(title: string): string {\n  return title.toLowerCase()\n    .replace(/[^a-z0-9\\s-]/g, '')\n    .replace(/\\s+/g, '-');\n}\n```\n\n### Reserved Windows Filenames\n```typescript\n// EDGE CASE: Windows reserved names cause file creation to fail\nconst reservedNames = ['CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'LPT1'];\n\nfunction isReservedWindowsName(filename: string): boolean {\n  const name = filename.toUpperCase().split('.')[0];\n  return reservedNames.includes(name);\n}\n\n// WORKAROUND: Prefix reserved names\nfunction sanitizeForWindows(filename: string): string {\n  if (isReservedWindowsName(filename)) {\n    return `kb-${filename}`;\n  }\n  return filename;\n}\n```\n\n## Complete Cross-Platform Path Handler\n```typescript\nimport { join, sep, posix } from 'path';\nimport { platform } from 'os';\n\nexport class CrossPlatformPathHandler {\n  private static readonly RESERVED_WINDOWS = [\n    'CON', 'PRN', 'AUX', 'NUL', 'COM1', 'COM2', 'COM3', 'COM4',\n    'COM5', 'COM6', 'COM7', 'COM8', 'COM9', 'LPT1', 'LPT2', 'LPT3'\n  ];\n\n  static normalizeForStorage(path: string): string {\n    // Always use forward slashes in stored JSON\n    return path.split(sep).join('/');\n  }\n\n  static normalizeForFileSystem(path: string): string {\n    // Use OS-appropriate separators for file operations\n    return path.split('/').join(sep);\n  }\n\n  static sanitizeFilename(filename: string): string {\n    let sanitized = filename\n      .replace(/[<>:\"|?*]/g, '') // Remove Windows invalid chars\n      .replace(/\\x00-\\x1f/g, '') // Remove control characters\n      .trim();\n\n    // Handle Windows reserved names\n    if (platform() === 'win32') {\n      const nameWithoutExt = sanitized.split('.')[0].toUpperCase();\n      if (this.RESERVED_WINDOWS.includes(nameWithoutExt)) {\n        sanitized = `kb-${sanitized}`;\n      }\n    }\n\n    return sanitized || 'untitled';\n  }\n}\n```",
  "tags": [
    "windows",
    "path",
    "edge-case",
    "cross-platform",
    "filesystem"
  ],
  "context": "This primarily affects Windows users or when the knowledge base is shared between Windows and Unix systems. The Node.js path module handles most cases, but JSON storage and string manipulation can still cause issues.",
  "created_at": "2025-08-03T17:47:00.393Z",
  "updated_at": "2025-08-04T11:15:19.959Z"
}