ForgeLM/.planning/phases/04-model-source-validation/04-03-PLAN.md

Plan 04-03: Validation UI and Recovery Experience

Wave: 2
Phase: 4
Requirements addressed: MODL-01, MODL-02

---

Objective

Implement inline validation UI and recovery guidance so users can understand and fix invalid model-source combinations before applying changes.

---

Read First

• tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx — settings form UI
• tauri-app/src/features/runtime/runtime-settings-form.ts — form state and validation
• tauri-app/src/features/runtime/types.ts — RuntimeDraftFieldMeta, RuntimeWorkspaceHealth
• .planning/phases/04-model-source-validation/04-RESEARCH.md — recovery guidance patterns

---

Action

1. Add validation message component in the settings drawer:

   Create or extend a validation message display:

   interface ValidationMessageProps {
     field: RuntimeDraftFieldKey;
     fieldState: RuntimeDraftFieldMeta;
     tone?: "warning" | "danger";
   }
   
   // Render below the relevant form field when fieldState.invalid is true
   // Show icon + message text
   // Use danger tone for errors, warning for recoverable issues
   

2. Show validation state in form fields:

   • Add visual indicator (red border) to invalid fields
   • Add validation message below each invalid field
   • Disable or warn when saving with invalid fields

3. Add recovery guidance for common issues:

   a) Model not in directory:

   "model_path" is not in the current models folder.
   Options:
   - Select a model from the list below
   - Browse to select a different model file
   - Change the models folder
   

   b) Models folder empty:

   No models found in this folder.
   Options:
   - Select a different folder
   - Add .gguf files to this folder
   - Import models from HuggingFace
   

   c) Invalid URL format:

   "server_url" must be a valid URL (https://...)
   

4. Integrate with lifecycle apply flow (from Phase 2):

   • Check field validation before allowing save/apply
   • Show "Cannot apply: fix validation errors first" if fields are invalid
   • Use applyImpact to determine if restart is needed after validation passes

5. Add model count badge in models dir field:

   • Show "📁 {dirName} ({count} models)" when scanned
   • Show "📁 {dirName} (scanning...)" during scan
   • Show "📁 {dirName} (no models)" when empty

---

Acceptance Criteria

• Invalid fields show red border and error message
• Validation messages appear below the relevant form field
• Recovery guidance provides clear next steps
• User cannot apply/save when critical fields are invalid
• Model count is displayed after successful scan
• Scanning shows loading state

---

Notes

• Reuse existing form field styling patterns
• Keep validation messages concise but actionable
• Consider accessibility (color-blind users should understand errors)
• Link to relevant documentation or help if needed
• Test with various invalid states: missing dir, invalid path, wrong mode