fix: handle YAML parsing edge cases in CustomModesManager (#5099)

* fix: handle YAML parsing edge cases in CustomModesManager

- Add BOM (Byte Order Mark) stripping for UTF-8 and UTF-16
- Normalize invisible characters including non-breaking spaces
- Replace fancy quotes and dashes with standard characters
- Remove zero-width characters that can cause parsing issues
- Add comprehensive test coverage for all edge cases

This fixes the YAML parsing limitations documented in PR #237 by
implementing proper preprocessing before parsing YAML content.

* fix: address PR review comments

- Fix BOM handling to correctly handle UTF-16 (all BOMs appear as \uFEFF when decoded)
- Optimize cleanInvisibleCharacters with single regex pass for better performance
- Prevent duplicate error messages by marking errors as already handled
- Refactor test file to use mockFsReadFile helper function to reduce duplication
- Fix YAML indentation in tests (use spaces instead of tabs)
- Add ESLint disable comment for character class warning (regex is correct)

* fix: prevent YAML line breaks by setting lineWidth to 0

- Added lineWidth: 0 option to all yaml.stringify() calls
- Prevents automatic line wrapping at 80 characters
- Improves readability of YAML output for long strings
- Applied to CustomModesManager, SimpleInstaller, and migrateSettings

* fix: add defaultStringType option to yaml.stringify calls

- Added defaultStringType: 'PLAIN' to minimize formatting changes
- This helps preserve plain scalars when possible
- Works alongside lineWidth: 0 to prevent automatic line wrapping

* refactor: extract problematic characters regex as a named constant

- Move regex pattern to PROBLEMATIC_CHARS_REGEX static constant
- Add comprehensive documentation for each character range
- Improves maintainability and makes the pattern reusable

* test: add comprehensive edge case tests for YAML parsing

- Add test for mixed line endings (CRLF vs LF)
- Add test for multiple BOMs in sequence
- Add test for deeply nested structures with problematic characters
- Ensures robustness across different real-world scenarios

* feat(i18n): add error messages for custom modes in multiple languages

* fix: update tests to expect i18n keys instead of hardcoded strings

- Update CustomModesManager tests to expect translation keys
- Fix YAML edge case tests to match new i18n error messages
- All tests now pass with the i18n integration

* refactor: use strip-bom package and fix error handling

- Replace custom stripBOM method with existing strip-bom package
- Fix duplicate error handling in parseYamlSafely by returning empty object instead of re-throwing
- Addresses review comments from PR #5099

---------

Co-authored-by: Daniel Riccio <[email protected]>

Author: hannesrudolph

src/core/config/CustomModesManager.ts

@@ -3,6 +3,7 @@ import * as path from "path"
 import * as fs from "fs/promises"
 
 import * as yaml from "yaml"
+import stripBom from "strip-bom"
 
 import { type ModeConfig, customModesSettingsSchema } from "@roo-code/types"
 
@@ -11,6 +12,7 @@ import { getWorkspacePath } from "../../utils/path"
 import { logger } from "../../utils/logging"
 import { GlobalFileNames } from "../../shared/globalFileNames"
 import { ensureSettingsDirectoryExists } from "../../utils/globalContext"
+import { t } from "../../i18n"
 
 const ROOMODES_FILENAME = ".roomodes"
 
@@ -73,12 +75,88 @@ export class CustomModesManager {
 		return exists ? roomodesPath : undefined
 	}
 
+	/**
+	 * Regex pattern for problematic characters that need to be cleaned from YAML content
+	 * Includes:
+	 * - \u00A0: Non-breaking space
+	 * - \u200B-\u200D: Zero-width spaces and joiners
+	 * - \u2010-\u2015, \u2212: Various dash characters
+	 * - \u2018-\u2019: Smart single quotes
+	 * - \u201C-\u201D: Smart double quotes
+	 */
+	private static readonly PROBLEMATIC_CHARS_REGEX =
+		// eslint-disable-next-line no-misleading-character-class
+		/[\u00A0\u200B\u200C\u200D\u2010\u2011\u2012\u2013\u2014\u2015\u2212\u2018\u2019\u201C\u201D]/g
+
+	/**
+	 * Clean invisible and problematic characters from YAML content
+	 */
+	private cleanInvisibleCharacters(content: string): string {
+		// Single pass replacement for all problematic characters
+		return content.replace(CustomModesManager.PROBLEMATIC_CHARS_REGEX, (match) => {
+			switch (match) {
+				case "\u00A0": // Non-breaking space
+					return " "
+				case "\u200B": // Zero-width space
+				case "\u200C": // Zero-width non-joiner
+				case "\u200D": // Zero-width joiner
+					return ""
+				case "\u2018": // Left single quotation mark
+				case "\u2019": // Right single quotation mark
+					return "'"
+				case "\u201C": // Left double quotation mark
+				case "\u201D": // Right double quotation mark
+					return '"'
+				default: // Dash characters (U+2010 through U+2015, U+2212)
+					return "-"
+			}
+		})
+	}
+
+	/**
+	 * Parse YAML content with enhanced error handling and preprocessing
+	 */
+	private parseYamlSafely(content: string, filePath: string): any {
+		// Clean the content
+		let cleanedContent = stripBom(content)
+		cleanedContent = this.cleanInvisibleCharacters(cleanedContent)
+
+		try {
+			return yaml.parse(cleanedContent)
+		} catch (error) {
+			const errorMsg = error instanceof Error ? error.message : String(error)
+			console.error(`[CustomModesManager] Failed to parse YAML from ${filePath}:`, errorMsg)
+
+			// Show user-friendly error message for .roomodes files
+			if (filePath.endsWith(ROOMODES_FILENAME)) {
+				const lineMatch = errorMsg.match(/at line (\d+)/)
+				const line = lineMatch ? lineMatch[1] : "unknown"
+				vscode.window.showErrorMessage(t("common:customModes.errors.yamlParseError", { line }))
+			}
+
+			// Return empty object to prevent duplicate error handling
+			return {}
+		}
+	}
+
 	private async loadModesFromFile(filePath: string): Promise<ModeConfig[]> {
 		try {
 			const content = await fs.readFile(filePath, "utf-8")
-			const settings = yaml.parse(content)
+			const settings = this.parseYamlSafely(content, filePath)
 			const result = customModesSettingsSchema.safeParse(settings)
+
 			if (!result.success) {
+				console.error(`[CustomModesManager] Schema validation failed for ${filePath}:`, result.error)
+
+				// Show user-friendly error for .roomodes files
+				if (filePath.endsWith(ROOMODES_FILENAME)) {
+					const issues = result.error.issues
+						.map((issue) => `• ${issue.path.join(".")}: ${issue.message}`)
+						.join("\n")
+
+					vscode.window.showErrorMessage(t("common:customModes.errors.schemaValidationError", { issues }))
+				}
+
 				return []
 			}
 
@@ -89,8 +167,11 @@ export class CustomModesManager {
 			// Add source to each mode
 			return result.data.customModes.map((mode) => ({ ...mode, source }))
 		} catch (error) {
-			const errorMsg = `Failed to load modes from ${filePath}: ${error instanceof Error ? error.message : String(error)}`
-			console.error(`[CustomModesManager] ${errorMsg}`)
+			// Only log if the error wasn't already handled in parseYamlSafely
+			if (!(error as any).alreadyHandled) {
+				const errorMsg = `Failed to load modes from ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+				console.error(`[CustomModesManager] ${errorMsg}`)
+			}
 			return []
 		}
 	}
@@ -124,7 +205,12 @@ export class CustomModesManager {
 		const fileExists = await fileExistsAtPath(filePath)
 
 		if (!fileExists) {
-			await this.queueWrite(() => fs.writeFile(filePath, yaml.stringify({ customModes: [] })))
+			await this.queueWrite(() =>
+				fs.writeFile(
+					filePath,
+					yaml.stringify({ customModes: [] }, { lineWidth: 0, defaultStringType: "PLAIN" }),
+				),
+			)
 		}
 
 		return filePath
@@ -147,13 +233,12 @@ export class CustomModesManager {
 				await this.getCustomModesFilePath()
 				const content = await fs.readFile(settingsPath, "utf-8")
 
-				const errorMessage =
-					"Invalid custom modes format. Please ensure your settings follow the correct YAML format."
+				const errorMessage = t("common:customModes.errors.invalidFormat")
 
 				let config: any
 
 				try {
-					config = yaml.parse(content)
+					config = this.parseYamlSafely(content, settingsPath)
 				} catch (error) {
 					console.error(error)
 					vscode.window.showErrorMessage(errorMessage)
@@ -284,7 +369,7 @@ export class CustomModesManager {
 
 				if (!workspaceFolders || workspaceFolders.length === 0) {
 					logger.error("Failed to update project mode: No workspace folder found", { slug })
-					throw new Error("No workspace folder found for project-specific mode")
+					throw new Error(t("common:customModes.errors.noWorkspaceForProject"))
 				}
 
 				const workspaceRoot = getWorkspacePath()
@@ -318,7 +403,7 @@ export class CustomModesManager {
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error)
 			logger.error("Failed to update custom mode", { slug, error: errorMessage })
-			vscode.window.showErrorMessage(`Failed to update custom mode: ${errorMessage}`)
+			vscode.window.showErrorMessage(t("common:customModes.errors.updateFailed", { error: errorMessage }))
 		}
 	}
 
@@ -329,20 +414,20 @@ export class CustomModesManager {
 			content = await fs.readFile(filePath, "utf-8")
 		} catch (error) {
 			// File might not exist yet.
-			content = yaml.stringify({ customModes: [] })
+			content = yaml.stringify({ customModes: [] }, { lineWidth: 0, defaultStringType: "PLAIN" })
 		}
 
 		let settings
 
 		try {
-			settings = yaml.parse(content)
+			settings = this.parseYamlSafely(content, filePath)
 		} catch (error) {
-			console.error(`[CustomModesManager] Failed to parse YAML from ${filePath}:`, error)
+			// Error already logged in parseYamlSafely
 			settings = { customModes: [] }
 		}
 
 		settings.customModes = operation(settings.customModes || [])
-		await fs.writeFile(filePath, yaml.stringify(settings), "utf-8")
+		await fs.writeFile(filePath, yaml.stringify(settings, { lineWidth: 0, defaultStringType: "PLAIN" }), "utf-8")
 	}
 
 	private async refreshMergedState(): Promise<void> {
@@ -373,7 +458,7 @@ export class CustomModesManager {
 			const globalMode = settingsModes.find((m) => m.slug === slug)
 
 			if (!projectMode && !globalMode) {
-				throw new Error("Write error: Mode not found")
+				throw new Error(t("common:customModes.errors.modeNotFound"))
 			}
 
 			await this.queueWrite(async () => {
@@ -392,23 +477,24 @@ export class CustomModesManager {
 				await this.refreshMergedState()
 			})
 		} catch (error) {
-			vscode.window.showErrorMessage(
-				`Failed to delete custom mode: ${error instanceof Error ? error.message : String(error)}`,
-			)
+			const errorMessage = error instanceof Error ? error.message : String(error)
+			vscode.window.showErrorMessage(t("common:customModes.errors.deleteFailed", { error: errorMessage }))
 		}
 	}
 
 	public async resetCustomModes(): Promise<void> {
 		try {
 			const filePath = await this.getCustomModesFilePath()
-			await fs.writeFile(filePath, yaml.stringify({ customModes: [] }))
+			await fs.writeFile(
+				filePath,
+				yaml.stringify({ customModes: [] }, { lineWidth: 0, defaultStringType: "PLAIN" }),
+			)
 			await this.context.globalState.update("customModes", [])
 			this.clearCache()
 			await this.onUpdate()
 		} catch (error) {
-			vscode.window.showErrorMessage(
-				`Failed to reset custom modes: ${error instanceof Error ? error.message : String(error)}`,
-			)
+			const errorMessage = error instanceof Error ? error.message : String(error)
+			vscode.window.showErrorMessage(t("common:customModes.errors.resetFailed", { error: errorMessage }))
 		}
 	}
 

src/core/config/__tests__/CustomModesManager.spec.ts

@@ -754,7 +754,7 @@ describe("CustomModesManager", () => {
 
 			await manager.deleteCustomMode("non-existent-mode")
 
-			expect(mockShowError).toHaveBeenCalledWith(expect.stringContaining("Write error"))
+			expect(mockShowError).toHaveBeenCalledWith("customModes.errors.deleteFailed")
 		})
 	})