diff --git a/cline_docs/settings.md b/cline_docs/settings.md index ce69076416c..cc04bd98481 100644 --- a/cline_docs/settings.md +++ b/cline_docs/settings.md @@ -183,39 +183,39 @@ These steps ensure that: To add a new configuration item to the system, the following changes are necessary: -1. **Feature-Specific Class** (if applicable) +1. **Feature-Specific Class** (if applicable) - For settings that affect specific features (e.g., Terminal, Browser, etc.) - Add a static property to store the value - Add getter/setter methods to access and modify the value -2. **Schema Definition** +2. **Schema Definition** - Add the item to globalSettingsSchema in schemas/index.ts - Add the item to globalSettingsRecord in schemas/index.ts -3. **Type Definitions** +3. **Type Definitions** - Add the item to exports/types.ts - Add the item to exports/roo-code.d.ts - Add the item to shared/ExtensionMessage.ts - Add the item to shared/WebviewMessage.ts -4. **UI Component** +4. **UI Component** - Create or update a component in webview-ui/src/components/settings/ - Add appropriate slider/input controls with min/max/step values - Ensure the props are passed correctly to the component in SettingsView.tsx - Update the component's props interface to include the new settings -5. **Translations** +5. **Translations** - Add label and description in webview-ui/src/i18n/locales/en/settings.json - Update all other languages - If any language content is changed, synchronize all other languages with that change - Translations must be performed within "translation" mode so change modes for that purpose -6. **State Management** +6. **State Management** - Add the item to the destructuring in SettingsView.tsx - Add the item to the handleSubmit function in SettingsView.tsx @@ -223,11 +223,11 @@ To add a new configuration item to the system, the following changes are necessa - Add the item to getState in ClineProvider.ts with appropriate default values - Add the item to the initialization in resolveWebviewView in ClineProvider.ts -7. **Message Handling** +7. **Message Handling** - Add a case for the item in webviewMessageHandler.ts -8. **Implementation-Specific Logic** +8. **Implementation-Specific Logic** - Implement any feature-specific behavior triggered by the setting - Examples: @@ -235,7 +235,7 @@ To add a new configuration item to the system, the following changes are necessa - API configuration changes for provider settings - UI behavior modifications for display settings -9. **Testing** +9. **Testing** - Add test cases for the new settings in appropriate test files - Verify settings persistence and state updates @@ -305,40 +305,139 @@ To add a new configuration item to the system, the following changes are necessa 11. **Debugging Settings Persistence Issues** - If a setting is not persisting across reload, check the following: + If a setting is not persisting across reload, check the following: - 1. **Complete Chain of Persistence**: + 1. **Complete Chain of Persistence**: - - Verify that the setting is added to all required locations: - - globalSettingsSchema and globalSettingsRecord in schemas/index.ts - - Initial state in ExtensionStateContextProvider - - getState method in ClineProvider.ts - - getStateToPostToWebview method in ClineProvider.ts - - resolveWebviewView method in ClineProvider.ts (if feature-specific) - - A break in any part of this chain can prevent persistence + - Verify that the setting is added to all required locations: + - globalSettingsSchema and globalSettingsRecord in schemas/index.ts + - Initial state in ExtensionStateContextProvider + - getState method in ClineProvider.ts + - getStateToPostToWebview method in ClineProvider.ts + - resolveWebviewView method in ClineProvider.ts (if feature-specific) + - A break in any part of this chain can prevent persistence - 2. **Default Values Consistency**: + 2. **Default Values Consistency**: - - Ensure default values are consistent across all locations - - Inconsistent defaults can cause unexpected behavior + - Ensure default values are consistent across all locations + - Inconsistent defaults can cause unexpected behavior - 3. **Message Handling**: + 3. **Message Handling**: - - Confirm the webviewMessageHandler.ts has a case for the setting - - Verify the message type matches what's sent from the UI + - Confirm the webviewMessageHandler.ts has a case for the setting + - Verify the message type matches what's sent from the UI - 4. **UI Integration**: + 4. **UI Integration**: - - Check that the setting is included in the handleSubmit function in SettingsView.tsx - - Ensure the UI component correctly updates the state + - Check that the setting is included in the handleSubmit function in SettingsView.tsx + - Ensure the UI component correctly updates the state - 5. **Type Definitions**: + 5. **Type Definitions**: - - Verify the setting is properly typed in all relevant interfaces - - Check for typos in property names across different files + - Verify the setting is properly typed in all relevant interfaces + - Check for typos in property names across different files - 6. **Storage Mechanism**: - - For complex settings, ensure proper serialization/deserialization - - Check that the setting is being correctly stored in VSCode's globalState + 6. **Storage Mechanism**: + - For complex settings, ensure proper serialization/deserialization + - Check that the setting is being correctly stored in VSCode's globalState These checks help identify and resolve common issues with settings persistence. + +12. **Advanced Troubleshooting: The Complete Settings Persistence Chain** + +Settings persistence requires a complete chain of state management across multiple components. Understanding this chain is critical for both humans and AI to effectively troubleshoot persistence issues: + +1. **Schema Definition (Entry Point)**: + + - Settings must be properly defined in `globalSettingsSchema` and `globalSettingsRecord` + - Enum values should use proper zod schemas: `z.enum(["value1", "value2"])` + - Example: + + ```typescript + // In schemas/index.ts + export const globalSettingsSchema = z.object({ + // Existing settings... + commandRiskLevel: z.enum(["readOnly", "reversibleChanges", "complexChanges"]).optional(), + }) + + const globalSettingsRecord: GlobalSettingsRecord = { + // Existing settings... + commandRiskLevel: undefined, + } + ``` + +2. **UI Component (User Interaction)**: + + - Must use consistent components (Select vs. select) with other similar settings + - Must use `setCachedStateField` for state updates, not direct state setting + - Must generate the correct message type through `vscode.postMessage` + - Example: + ```tsx + // In a settings component + + ``` + +3. **Message Handler (State Saving)**: + + - Must use correct message type in `webviewMessageHandler.ts` + - Must use `updateGlobalState` with properly typed values + - Must call `postStateToWebview` after updates + - Example: + ```typescript + // In webviewMessageHandler.ts + case "commandRiskLevel": + await updateGlobalState( + "commandRiskLevel", + (message.text ?? "readOnly") as "readOnly" | "reversibleChanges" | "complexChanges" + ) + await provider.postStateToWebview() + break + ``` + +4. **State Retrieval (Reading State)**: + + - In `getState`, state must be properly retrieved from stateValues + - In `getStateToPostToWebview`, the setting must be in the destructured parameters + - The setting must be included in the return value + - Use `contextProxy.getGlobalState` for direct access when needed + - Example: + + ```typescript + // In ClineProvider.ts getStateToPostToWebview + const { + // Other state properties... + commandRiskLevel, + } = await this.getState() + + return { + // Other state properties... + commandRiskLevel: commandRiskLevel ?? "readOnly", + } + ``` + +5. **Debugging Strategies**: + + - **Follow the State Flow**: Watch the setting's value at each step in the chain + - **Type Safety**: Ensure the same type is used throughout the chain + - **Component Consistency**: Use the same pattern as other working settings + - **Check Return Values**: Ensure the setting is included in all return objects + - **State vs. Configuration**: Understand when to use state vs. VSCode configuration + +6. **Common Pitfalls**: + - **Type Mismatch**: Using string where an enum is expected + - **Chain Breaks**: Missing the setting in return objects + - **UI Inconsistency**: Using different component patterns + - **DefaultValue Issues**: Inconsistent default values across components + - **Missing Schema**: Not adding to schema or record definitions + +Remember: A break at ANY point in this chain can cause persistence failures. When troubleshooting, systematically check each link in the chain to identify where the issue occurs.