refactor: implement reset-to-default pattern with centralized defaults

- Add settingDefaults registry in packages/types/src/defaults.ts
- Add settings migration framework with versioned migrations
- Flatten codebaseIndexConfig to top-level keys for consistency
- Create new IndexingSettings UI component in Settings view
- Update SettingsView to pass undefined instead of coerced defaults
- Update ExtensionStateContext types to support optional settings
- Add comprehensive tests for defaults and migrations

Author: hannesrudolph

packages/types/src/__tests__/defaults.spec.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest"
+import { settingDefaults, getSettingWithDefault } from "../defaults.js"
+import { DEFAULT_CHECKPOINT_TIMEOUT_SECONDS } from "../global-settings.js"
+
+describe("settingDefaults", () => {
+	it("should have all expected default values", () => {
+		// Browser settings
+		expect(settingDefaults.browserToolEnabled).toBe(true)
+		expect(settingDefaults.browserViewportSize).toBe("900x600")
+		expect(settingDefaults.remoteBrowserEnabled).toBe(false)
+		expect(settingDefaults.screenshotQuality).toBe(75)
+
+		// Audio/TTS settings
+		expect(settingDefaults.soundEnabled).toBe(true)
+		expect(settingDefaults.soundVolume).toBe(0.5)
+		expect(settingDefaults.ttsEnabled).toBe(true)
+		expect(settingDefaults.ttsSpeed).toBe(1.0)
+
+		// Diff/Editor settings
+		expect(settingDefaults.diffEnabled).toBe(true)
+		expect(settingDefaults.fuzzyMatchThreshold).toBe(1.0)
+
+		// Checkpoint settings
+		expect(settingDefaults.enableCheckpoints).toBe(false)
+		expect(settingDefaults.checkpointTimeout).toBe(DEFAULT_CHECKPOINT_TIMEOUT_SECONDS)
+
+		// Terminal settings
+		expect(settingDefaults.terminalOutputLineLimit).toBe(500)
+		expect(settingDefaults.terminalOutputCharacterLimit).toBe(50_000)
+		expect(settingDefaults.terminalShellIntegrationTimeout).toBe(30_000)
+
+		// Context management settings
+		expect(settingDefaults.maxOpenTabsContext).toBe(20)
+		expect(settingDefaults.maxWorkspaceFiles).toBe(200)
+		expect(settingDefaults.showRooIgnoredFiles).toBe(false)
+		expect(settingDefaults.enableSubfolderRules).toBe(false)
+		expect(settingDefaults.maxReadFileLine).toBe(-1)
+		expect(settingDefaults.maxImageFileSize).toBe(5)
+		expect(settingDefaults.maxTotalImageSize).toBe(20)
+		expect(settingDefaults.maxConcurrentFileReads).toBe(5)
+
+		// Diagnostic settings
+		expect(settingDefaults.includeDiagnosticMessages).toBe(true)
+		expect(settingDefaults.maxDiagnosticMessages).toBe(50)
+
+		// Auto-approval settings
+		expect(settingDefaults.alwaysAllowFollowupQuestions).toBe(false)
+
+		// Prompt enhancement settings
+		expect(settingDefaults.condensingApiConfigId).toBe("")
+		expect(settingDefaults.includeTaskHistoryInEnhance).toBe(true)
+
+		// UI settings
+		expect(settingDefaults.reasoningBlockCollapsed).toBe(true)
+		expect(settingDefaults.enterBehavior).toBe("send")
+
+		// Environment details settings
+		expect(settingDefaults.includeCurrentTime).toBe(true)
+		expect(settingDefaults.includeCurrentCost).toBe(true)
+		expect(settingDefaults.maxGitStatusFiles).toBe(0)
+
+		// Language settings
+		expect(settingDefaults.language).toBe("en")
+
+		// MCP settings
+		expect(settingDefaults.mcpEnabled).toBe(true)
+	})
+
+	it("should be immutable (readonly)", () => {
+		// TypeScript should prevent this at compile time, but we can verify the type
+		const defaultsCopy = { ...settingDefaults }
+		expect(defaultsCopy.browserToolEnabled).toBe(settingDefaults.browserToolEnabled)
+	})
+})
+
+describe("getSettingWithDefault", () => {
+	it("should return the value when defined (matching type)", () => {
+		// Test with values that match the default type
+		expect(getSettingWithDefault("browserToolEnabled", true)).toBe(true)
+		expect(getSettingWithDefault("soundVolume", 0.5)).toBe(0.5)
+		expect(getSettingWithDefault("maxOpenTabsContext", 20)).toBe(20)
+		expect(getSettingWithDefault("enterBehavior", "send")).toBe("send")
+	})
+
+	it("should return the default when value is undefined", () => {
+		expect(getSettingWithDefault("browserToolEnabled", undefined)).toBe(true)
+		expect(getSettingWithDefault("soundVolume", undefined)).toBe(0.5)
+		expect(getSettingWithDefault("maxOpenTabsContext", undefined)).toBe(20)
+		expect(getSettingWithDefault("enterBehavior", undefined)).toBe("send")
+		expect(getSettingWithDefault("mcpEnabled", undefined)).toBe(true)
+		expect(getSettingWithDefault("showRooIgnoredFiles", undefined)).toBe(false)
+	})
+
+	it("should demonstrate reset-to-default pattern", () => {
+		// This test demonstrates the ideal "reset to default" pattern:
+		// When a user resets a setting, we store `undefined` (not the default value)
+		// When reading, we apply the default at consumption time
+
+		// Simulating reading from storage where value is undefined (reset state)
+		const storedValue = undefined
+		const effectiveValue = getSettingWithDefault("browserToolEnabled", storedValue)
+
+		// User sees the default value
+		expect(effectiveValue).toBe(true)
+
+		// If the default changes in the future (e.g., to false),
+		// users who reset their setting would automatically get the new default
+		// because they stored `undefined`, not `true`
+	})
+})

packages/types/src/defaults.ts

@@ -0,0 +1,144 @@
+/**
+ * Centralized defaults registry for Roo Code settings.
+ *
+ * IMPORTANT: These defaults should be applied at READ time (when consuming state),
+ * NOT at WRITE time (when saving settings). This ensures:
+ * - Users who haven't customized a setting inherit future default improvements
+ * - Storage only contains intentional user customizations, not copies of defaults
+ * - "Reset to Default" properly removes settings from storage (sets to undefined)
+ *
+ * Pattern:
+ * - On save: pass `undefined` to remove a setting from storage (reset to default)
+ * - On read: apply defaults using `value ?? settingDefaults.settingName`
+ */
+
+import { DEFAULT_CHECKPOINT_TIMEOUT_SECONDS } from "./global-settings.js"
+
+/**
+ * Default values for all settings that can be reset to default.
+ *
+ * These values are the source of truth for defaults throughout the application.
+ * When a setting is undefined in storage, these defaults should be applied
+ * at consumption time.
+ */
+export const settingDefaults = {
+	// Browser settings
+	browserToolEnabled: true,
+	browserViewportSize: "900x600",
+	remoteBrowserEnabled: false,
+	screenshotQuality: 75,
+
+	// Audio/TTS settings
+	soundEnabled: true,
+	soundVolume: 0.5,
+	ttsEnabled: true,
+	ttsSpeed: 1.0,
+
+	// Diff/Editor settings
+	diffEnabled: true,
+	fuzzyMatchThreshold: 1.0,
+
+	// Checkpoint settings
+	enableCheckpoints: false,
+	checkpointTimeout: DEFAULT_CHECKPOINT_TIMEOUT_SECONDS,
+
+	// Terminal settings
+	terminalOutputLineLimit: 500,
+	terminalOutputCharacterLimit: 50_000,
+	terminalShellIntegrationTimeout: 30_000,
+
+	// Context management settings
+	maxOpenTabsContext: 20,
+	maxWorkspaceFiles: 200,
+	showRooIgnoredFiles: false,
+	enableSubfolderRules: false,
+	maxReadFileLine: -1,
+	maxImageFileSize: 5,
+	maxTotalImageSize: 20,
+	maxConcurrentFileReads: 5,
+
+	// Diagnostic settings
+	includeDiagnosticMessages: true,
+	maxDiagnosticMessages: 50,
+	writeDelayMs: 1000,
+
+	// Auto-approval settings
+	alwaysAllowFollowupQuestions: false,
+
+	// Prompt enhancement settings
+	condensingApiConfigId: "",
+	includeTaskHistoryInEnhance: true,
+
+	// UI settings
+	reasoningBlockCollapsed: true,
+	enterBehavior: "send" as const,
+
+	// Environment details settings
+	includeCurrentTime: true,
+	includeCurrentCost: true,
+	maxGitStatusFiles: 0,
+
+	// Language settings
+	language: "en" as const,
+
+	// MCP settings
+	mcpEnabled: true,
+
+	// Indexing settings
+	codebaseIndexEnabled: false,
+	codebaseIndexQdrantUrl: "http://localhost:6333",
+	codebaseIndexEmbedderProvider: "openai" as const,
+	codebaseIndexEmbedderBaseUrl: "",
+	codebaseIndexEmbedderModelId: "",
+	codebaseIndexEmbedderModelDimension: 1536,
+	codebaseIndexOpenAiCompatibleBaseUrl: "",
+	codebaseIndexBedrockRegion: "us-east-1",
+	codebaseIndexBedrockProfile: "",
+	codebaseIndexSearchMaxResults: 100,
+	codebaseIndexSearchMinScore: 0.4,
+	codebaseIndexOpenRouterSpecificProvider: "",
+} as const
+
+/**
+ * Type representing all setting keys that have defaults.
+ */
+export type SettingWithDefault = keyof typeof settingDefaults
+
+/**
+ * Helper function to get a setting value with its default applied.
+ * Use this when reading settings from storage.
+ *
+ * @param key - The setting key
+ * @param value - The value from storage (may be undefined)
+ * @returns The value if defined, otherwise the default
+ *
+ * @example
+ * const browserToolEnabled = getSettingWithDefault('browserToolEnabled', storedValue)
+ */
+export function getSettingWithDefault<K extends SettingWithDefault>(
+	key: K,
+	value: (typeof settingDefaults)[K] | undefined,
+): (typeof settingDefaults)[K] {
+	return value ?? settingDefaults[key]
+}
+
+/**
+ * Applies defaults to a partial settings object.
+ * Only applies defaults for settings that are undefined.
+ *
+ * @param settings - Partial settings object
+ * @returns Settings object with defaults applied for undefined values
+ */
+export function applySettingDefaults<T extends Partial<Record<SettingWithDefault, unknown>>>(
+	settings: T,
+): T & typeof settingDefaults {
+	const result = { ...settings } as T & typeof settingDefaults
+
+	for (const key of Object.keys(settingDefaults) as SettingWithDefault[]) {
+		if (result[key] === undefined) {
+			;(result as Record<SettingWithDefault, unknown>)[key] = settingDefaults[key]
+		}
+	}
+
+	return result
+}

packages/types/src/global-settings.ts

@@ -169,6 +169,31 @@ export const globalSettingsSchema = z.object({
 	codebaseIndexModels: codebaseIndexModelsSchema.optional(),
 	codebaseIndexConfig: codebaseIndexConfigSchema.optional(),
 
+	// Indexing settings (flattened from codebaseIndexConfig for reset-to-default pattern)
+	codebaseIndexEnabled: z.boolean().optional(),
+	codebaseIndexQdrantUrl: z.string().optional(),
+	codebaseIndexEmbedderProvider: z
+		.enum([
+			"openai",
+			"ollama",
+			"openai-compatible",
+			"gemini",
+			"mistral",
+			"vercel-ai-gateway",
+			"bedrock",
+			"openrouter",
+		])
+		.optional(),
+	codebaseIndexEmbedderBaseUrl: z.string().optional(),
+	codebaseIndexEmbedderModelId: z.string().optional(),
+	codebaseIndexEmbedderModelDimension: z.number().optional(),
+	codebaseIndexOpenAiCompatibleBaseUrl: z.string().optional(),
+	codebaseIndexBedrockRegion: z.string().optional(),
+	codebaseIndexBedrockProfile: z.string().optional(),
+	codebaseIndexSearchMaxResults: z.number().optional(),
+	codebaseIndexSearchMinScore: z.number().optional(),
+	codebaseIndexOpenRouterSpecificProvider: z.string().optional(),
+
 	language: languagesSchema.optional(),
 
 	telemetrySetting: telemetrySettingsSchema.optional(),
@@ -205,6 +230,13 @@ export const globalSettingsSchema = z.object({
 	 * Used by the worktree feature to open the Roo Code sidebar in a new window.
 	 */
 	worktreeAutoOpenPath: z.string().optional(),
+
+	/**
+	 * Version of settings migrations that have been applied.
+	 * Used to track which migrations have run to avoid re-running them.
+	 * @internal
+	 */
+	settingsMigrationVersion: z.number().optional(),
 })
 
 export type GlobalSettings = z.infer<typeof globalSettingsSchema>

packages/types/src/index.ts

@@ -7,6 +7,7 @@ export * from "./custom-tool.js"
 export * from "./embedding.js"
 export * from "./events.js"
 export * from "./experiment.js"
+export * from "./defaults.js"
 export * from "./followup.js"
 export * from "./git.js"
 export * from "./global-settings.js"

packages/types/src/vscode-extension-host.ts

@@ -352,19 +352,21 @@ export type ExtensionState = Pick<
 
 	writeDelayMs: number
 
-	enableCheckpoints: boolean
-	checkpointTimeout: number // Timeout for checkpoint initialization in seconds (default: 15)
-	maxOpenTabsContext: number // Maximum number of VSCode open tabs to include in context (0-500)
-	maxWorkspaceFiles: number // Maximum number of files to include in current working directory details (0-500)
-	showRooIgnoredFiles: boolean // Whether to show .rooignore'd files in listings
-	enableSubfolderRules: boolean // Whether to load rules from subdirectories
-	maxReadFileLine: number // Maximum number of lines to read from a file before truncating
-	maxImageFileSize: number // Maximum size of image files to process in MB
-	maxTotalImageSize: number // Maximum total size for all images in a single read operation in MB
+	// These fields are optional to support the "reset to default" pattern.
+	// When undefined, consumers should apply defaults from settingDefaults.
+	enableCheckpoints?: boolean
+	checkpointTimeout?: number // Timeout for checkpoint initialization in seconds (default: 15)
+	maxOpenTabsContext?: number // Maximum number of VSCode open tabs to include in context (0-500)
+	maxWorkspaceFiles?: number // Maximum number of files to include in current working directory details (0-500)
+	showRooIgnoredFiles?: boolean // Whether to show .rooignore'd files in listings
+	enableSubfolderRules?: boolean // Whether to load rules from subdirectories
+	maxReadFileLine?: number // Maximum number of lines to read from a file before truncating
+	maxImageFileSize?: number // Maximum size of image files to process in MB
+	maxTotalImageSize?: number // Maximum total size for all images in a single read operation in MB
 
 	experiments: Experiments // Map of experiment IDs to their enabled state
 
-	mcpEnabled: boolean
+	mcpEnabled?: boolean
 	enableMcpServerCreation: boolean
 
 	mode: string
@@ -543,7 +545,9 @@ export interface WebviewMessage {
 		| "condenseTaskContextRequest"
 		| "requestIndexingStatus"
 		| "startIndexing"
+		| "stopIndexing"
 		| "clearIndexData"
+		| "openSettings"
 		| "indexingStatusUpdate"
 		| "indexCleared"
 		| "focusPanelRequest"
@@ -609,6 +613,7 @@ export interface WebviewMessage {
 		| "checkoutBranch"
 		| "mergeWorktree"
 	text?: string
+	section?: string // For openSettings: the target section/tab to open
 	editedMessageContent?: string
 	tab?: "settings" | "history" | "mcp" | "modes" | "chat" | "marketplace" | "cloud"
 	disabled?: boolean

src/core/config/ContextProxy.ts

@@ -21,6 +21,7 @@ import { TelemetryService } from "@roo-code/telemetry"
 
 import { logger } from "../../utils/logging"
 import { supportPrompt } from "../../shared/support-prompt"
+import { runSettingsMigrations } from "../../utils/settingsMigrations"
 
 type GlobalStateKey = keyof GlobalState
 type SecretStateKey = keyof SecretState
@@ -96,6 +97,9 @@ export class ContextProxy {
 		// Migration: Move legacy customCondensingPrompt to customSupportPrompts
 		await this.migrateLegacyCondensingPrompt()
 
+		// Migration: Clear hardcoded defaults so users can benefit from future default changes
+		await runSettingsMigrations(this)
+
 		this._isInitialized = true
 	}
 

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

@@ -390,14 +390,13 @@ describe("ContextProxy", () => {
 			// Reset all state
 			await proxy.resetAllState()
 
-			// Should have called update with undefined for each key
+			// Should have called update with undefined for each key during reset
 			for (const key of GLOBAL_STATE_KEYS) {
 				expect(mockGlobalState.update).toHaveBeenCalledWith(key, undefined)
 			}
 
-			// Total calls should include initial setup + reset operations
-			const expectedUpdateCalls = 2 + GLOBAL_STATE_KEYS.length
-			expect(mockGlobalState.update).toHaveBeenCalledTimes(expectedUpdateCalls)
+			// Note: Total call count varies based on migrations that run during initialize().
+			// Instead of checking exact counts, we verify all keys were set to undefined above.
 		})
 
 		it("should delete all secrets", async () => {