@michelabboud/visual-forge-mcp 0.5.5 → 0.6.0

package/docs/guides/backup-system.md

@@ -0,0 +1,688 @@
+# Visual Forge MCP - Backup System
+
+## Overview
+
+The backup system provides automatic, transparent file backup and restoration capabilities for Visual Forge MCP. It ensures users can safely revert changes if needed while maintaining a clean, intuitive workflow.
+
+## Features
+
+✅ **Automatic backups** before modifying markdown files
+✅ **Backup generated images** alongside markdown files
+✅ **Integrity verification** with MD5 hashing
+✅ **24-hour reminders** for pending backups
+✅ **Atomic operations** for backup/restore
+✅ **State persistence** across sessions
+✅ **Enable/disable switch** (VF_BACKUP_ENABLED)
+✅ **MCP tool integration** (approve, restore, list)
+
+## Configuration
+
+### Environment Variable
+
+```bash
+# Enable/disable backups (default: true)
+VF_BACKUP_ENABLED=true
+
+# Disable backups
+VF_BACKUP_ENABLED=false
+```
+
+### Configuration Object
+
+```typescript
+{
+  enabled: true,                    // Enable backups
+  extension: '.vf-bak',            // Backup file extension
+  reminderIntervalHours: 24,       // Reminder frequency
+}
+```
+
+## How It Works
+
+### 1. Backup Creation
+
+When Visual Forge modifies files, it automatically creates backups:
+
+```
+Original Files:
+docs/README.md
+generated-images/diagram-001.png
+
+Backup Files Created:
+docs/README.md.vf-bak
+generated-images/diagram-001.png.vf-bak
+```
+
+Each backup includes:
+- Original file path
+- Backup file path
+- Timestamp
+- File size
+- MD5 hash (for integrity verification)
+- File type (markdown or image)
+
+### 2. State Tracking
+
+Backups are tracked in the StateManager:
+
+```typescript
+{
+  backups: {
+    current: BackupSet | null,     // Active backup set
+    history: [                     // Past backups
+      {
+        id: "backup-uuid",
+        createdAt: "2026-01-13T...",
+        action: "approved",
+        actionAt: "2026-01-13T...",
+        filesCount: 8
+      }
+    ]
+  }
+}
+```
+
+### 3. User Workflow
+
+```
+1. User generates images
+   ↓
+2. Visual Forge creates backups (transparent)
+   ↓
+3. Visual Forge modifies markdown files
+   ↓
+4. User reviews changes
+   ↓
+5a. Approve → Delete backups        5b. Restore → Undo changes
+```
+
+## MCP Tools
+
+### 1. `approve_changes`
+
+**Description**: Approve changes and delete backup files (keeps modifications)
+
+**Input**: None
+
+**Output**:
+```json
+{
+  "success": true,
+  "message": "Changes approved successfully",
+  "filesDeleted": 8,
+  "backupId": "abc-123-def"
+}
+```
+
+**Use Case**: User is happy with generated images and wants to keep changes
+
+**Example**:
+```
+User: "The images look great! I'll keep these changes."
+AI: Calling approve_changes...
+Response: "✓ Changes approved! Deleted 8 backup files."
+```
+
+---
+
+### 2. `restore_from_backups`
+
+**Description**: Restore files from backups (undoes all changes)
+
+**Input**: None
+
+**Output**:
+```json
+{
+  "success": true,
+  "message": "All files restored successfully",
+  "filesRestored": 8,
+  "errors": [],
+  "backupId": "abc-123-def"
+}
+```
+
+**Use Case**: User wants to undo changes and go back to original state
+
+**Example**:
+```
+User: "Actually, I don't like these images. Can we start over?"
+AI: Calling restore_from_backups...
+Response: "✓ Restored 8 files from backup. All changes undone."
+```
+
+---
+
+### 3. `list_backups`
+
+**Description**: Show current backup status and details
+
+**Input**: None
+
+**Output (with pending backups)**:
+```json
+{
+  "hasPendingBackups": true,
+  "current": {
+    "id": "abc-123-def",
+    "createdAt": "2026-01-13T08:00:00Z",
+    "markdownFiles": 3,
+    "imageFiles": 5,
+    "totalFiles": 8,
+    "totalSize": 524288,
+    "lastRemindedAt": null,
+    "needsReminder": false
+  },
+  "summary": "📸 Backup: abc-123-def\n   Created: 2 hours ago\n   Files: 3 markdown, 5 images\n   Size: 512.00 KB",
+  "actions": {
+    "approve": "Call approve_changes to keep modifications",
+    "restore": "Call restore_from_backups to undo all changes"
+  },
+  "history": [],
+  "backupEnabled": true
+}
+```
+
+**Output (no pending backups)**:
+```json
+{
+  "hasPendingBackups": false,
+  "message": "No pending backups",
+  "history": [
+    {
+      "id": "xyz-456-abc",
+      "createdAt": "2026-01-12T10:00:00Z",
+      "action": "approved",
+      "actionAt": "2026-01-12T11:00:00Z",
+      "filesCount": 5
+    }
+  ],
+  "backupEnabled": true
+}
+```
+
+**Use Case**: Check if there are pending backups and their details
+
+**Example**:
+```
+User: "Do I have any pending changes to review?"
+AI: Calling list_backups...
+Response: "You have 8 files backed up (3 markdown, 5 images) from 2 hours ago.
+          To keep: call approve_changes
+          To undo: call restore_from_backups"
+```
+
+---
+
+## Architecture
+
+### Component Structure
+
+```
+src/
+├── backup/
+│   └── backup-manager.ts         # Core backup logic
+├── types/
+│   └── backup.ts                 # Type definitions
+├── state/
+│   └── state-manager.ts          # State persistence (extended)
+└── server/
+    └── mcp-server.ts             # MCP tools (extended)
+```
+
+### Class: BackupManager
+
+**Location**: `src/backup/backup-manager.ts`
+
+**Key Methods**:
+
+```typescript
+class BackupManager {
+  // Create backups for specified files
+  async createBackup(
+    markdownFiles: string[],
+    imageFiles: string[]
+  ): Promise<BackupResult>
+
+  // Restore files from backup set
+  async restoreFromBackup(
+    backupSet: BackupSet
+  ): Promise<RestoreResult>
+
+  // Approve changes (delete backups)
+  async approveChanges(
+    backupSet: BackupSet
+  ): Promise<ApprovalResult>
+
+  // Check if reminder needed
+  shouldRemind(backupSet: BackupSet): boolean
+
+  // Get human-readable summary
+  getBackupSummary(backupSet: BackupSet): string
+
+  // Verify backup integrity
+  async verifyBackup(backupFile: BackupFile): Promise<boolean>
+
+  // Get/set configuration
+  getConfig(): BackupConfig
+  setConfig(config: Partial<BackupConfig>): void
+}
+```
+
+### StateManager Extensions
+
+**Added Methods**:
+
+```typescript
+class StateManager {
+  // Set current backup set
+  setCurrentBackup(backupSet: BackupSet): void
+
+  // Get current backup set
+  getCurrentBackup(): BackupSet | null
+
+  // Clear backup after approval/restore
+  clearCurrentBackup(action: 'approved' | 'restored'): void
+
+  // Update reminder timestamp
+  updateBackupReminder(): void
+
+  // Check for pending backups
+  hasPendingBackups(): boolean
+
+  // Get backup history
+  getBackupHistory(): Array<...>
+}
+```
+
+### Type Definitions
+
+**Location**: `src/types/backup.ts`
+
+**Key Types**:
+
+```typescript
+interface BackupFile {
+  originalPath: string;
+  backupPath: string;
+  timestamp: string;
+  size: number;
+  type: 'markdown' | 'image';
+  hash: string;
+}
+
+interface BackupSet {
+  id: string;
+  createdAt: string;
+  lastRemindedAt?: string;
+  markdownFiles: BackupFile[];
+  imageFiles: BackupFile[];
+  totalFiles: number;
+  totalSize: number;
+  approved: boolean;
+  sessionId?: string;
+}
+
+interface BackupState {
+  current: BackupSet | null;
+  history: Array<{
+    id: string;
+    createdAt: string;
+    action: 'approved' | 'restored';
+    actionAt: string;
+    filesCount: number;
+  }>;
+}
+```
+
+---
+
+## Workflow Integration
+
+### When Backups Are Created
+
+Backups are created automatically when:
+
+1. **Before markdown modification**: When updating markdown files with image references
+2. **After image generation**: When new images are created
+
+### Example Workflow
+
+```typescript
+// 1. User starts workflow
+await workflowOrchestrator.start();
+
+// 2. Generate images
+const images = await generateImages(specs);
+
+// 3. CREATE BACKUP (automatic)
+const backupResult = await backupManager.createBackup(
+  ['docs/README.md'],
+  images.map(img => img.path)
+);
+
+// 4. Store backup in state
+stateManager.setCurrentBackup(backupResult.backupSet);
+await stateManager.save();
+
+// 5. Modify markdown files
+await updateMarkdownFiles(images);
+
+// 6. User reviews changes
+// ... user can approve or restore ...
+```
+
+---
+
+## Backup File Format
+
+### Backup Extension
+
+All backups use the `.vf-bak` extension:
+
+```
+original-file.md       → original-file.md.vf-bak
+diagram-001.png        → diagram-001.png.vf-bak
+```
+
+### Backup Location
+
+Backups are stored **alongside original files**:
+
+```
+project/
+├── docs/
+│   ├── README.md
+│   └── README.md.vf-bak           ← Backup
+├── generated-images/
+│   ├── diagram-001.png
+│   └── diagram-001.png.vf-bak     ← Backup
+```
+
+This ensures:
+- ✅ Backups stay with their files
+- ✅ Easy to find and manage
+- ✅ Works with any directory structure
+
+---
+
+## Integrity Verification
+
+### MD5 Hash Verification
+
+Every backup includes an MD5 hash of the original file:
+
+```typescript
+{
+  originalPath: "docs/README.md",
+  backupPath: "docs/README.md.vf-bak",
+  hash: "5d41402abc4b2a76b9719d911017c592"
+}
+```
+
+**When restoring:**
+1. Read backup file
+2. Calculate MD5 hash
+3. Compare with stored hash
+4. Warn if mismatch (file modified after backup)
+
+### Atomic Operations
+
+**Backup Creation**:
+1. Read original file
+2. Calculate hash
+3. Copy to `.vf-bak`
+4. Verify copy successful
+5. Store in state
+
+**Restoration**:
+1. Verify backup exists
+2. Verify backup integrity (hash)
+3. Copy backup → original
+4. Delete backup file
+5. Update state
+
+---
+
+## 24-Hour Reminder System
+
+### How Reminders Work
+
+1. Backup created at `T0`
+2. User calls `list_backups` at `T0 + 25 hours`
+3. System detects 24 hours passed
+4. Sets `needsReminder: true` in response
+5. Updates `lastRemindedAt` timestamp
+6. Next reminder at `T0 + 49 hours`
+
+### Reminder Logic
+
+```typescript
+shouldRemind(backupSet: BackupSet): boolean {
+  const now = Date.now();
+  const createdAt = new Date(backupSet.createdAt).getTime();
+  const lastRemindedAt = backupSet.lastRemindedAt
+    ? new Date(backupSet.lastRemindedAt).getTime()
+    : createdAt;
+
+  const hoursSinceLastReminder =
+    (now - lastRemindedAt) / (1000 * 60 * 60);
+
+  return hoursSinceLastReminder >= 24;
+}
+```
+
+### Reminder Message Example
+
+```
+⏰ Reminder: You have unapproved changes (created 24 hours ago)
+   - 3 markdown files backed up
+   - 5 images backed up
+
+   Actions:
+   - approve_changes     → Keep changes, delete backups
+   - restore_from_backups → Undo all changes
+```
+
+---
+
+## Error Handling
+
+### Backup Creation Failures
+
+```typescript
+{
+  success: false,
+  filesBackedUp: 0,
+  error: "Failed to read file: docs/README.md"
+}
+```
+
+**Cause**: File permissions, missing file, disk full
+
+**Resolution**: Check file exists, fix permissions, free disk space
+
+### Restore Failures
+
+```typescript
+{
+  success: false,
+  filesRestored: 2,
+  errors: [
+    {
+      file: "docs/GUIDE.md",
+      error: "Backup file not found"
+    }
+  ]
+}
+```
+
+**Cause**: Backup file deleted manually, corrupted
+
+**Resolution**: Partial restore succeeded, review errors
+
+### Approval Failures
+
+```typescript
+{
+  success: false,
+  filesDeleted: 3,
+  errors: [
+    {
+      file: "docs/README.md.vf-bak",
+      error: "Permission denied"
+    }
+  ]
+}
+```
+
+**Cause**: File permissions, file in use
+
+**Resolution**: Fix permissions, close files
+
+---
+
+## Best Practices
+
+### For Users
+
+1. **Review regularly**: Check `list_backups` to see pending changes
+2. **Approve or restore**: Don't leave backups pending indefinitely
+3. **Keep enabled**: Leave `VF_BACKUP_ENABLED=true` for safety
+4. **Check reminders**: Respond to 24-hour reminder notifications
+
+### For Developers
+
+1. **Always create backups**: Before any file modification
+2. **Store in state**: Use StateManager to track backups
+3. **Handle errors**: Catch backup/restore errors gracefully
+4. **Verify integrity**: Check MD5 hashes on restore
+5. **Clean up**: Delete backups after approval/restore
+
+---
+
+## Testing
+
+### Manual Testing
+
+```bash
+# 1. Generate images (creates backups)
+# User: "Generate diagrams for docs/README.md"
+
+# 2. List backups
+# User: "Show me the backup status"
+# AI calls: list_backups
+
+# 3. Restore changes
+# User: "I don't like these, restore original"
+# AI calls: restore_from_backups
+
+# 4. Generate again and approve
+# User: "These look great, keep them"
+# AI calls: approve_changes
+```
+
+### Automated Testing
+
+```bash
+# Run backup tests
+npm test test/backup/
+
+# Test scenarios:
+# - Backup creation
+# - Backup restoration
+# - Approval workflow
+# - Integrity verification
+# - Reminder system
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Backups not created
+
+**Check**:
+```bash
+# Verify enabled
+echo $VF_BACKUP_ENABLED  # Should be "true" or empty (default true)
+
+# Check logs
+tail -f ~/.visual-forge-mcp/logs/visual-forge.log
+```
+
+### Issue: Cannot restore backups
+
+**Check**:
+```bash
+# Verify backup files exist
+ls -la docs/*.vf-bak
+
+# Check file permissions
+chmod 644 docs/*.vf-bak
+```
+
+### Issue: Backup files remain after approval
+
+**Manually clean**:
+```bash
+# Remove all backup files
+find . -name "*.vf-bak" -delete
+
+# Clear state
+rm ~/.visual-forge-mcp/state.json
+```
+
+---
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Compression**: Compress backup files to save space
+2. **Retention policy**: Auto-delete old backups after N days
+3. **Selective restore**: Restore individual files instead of all
+4. **Backup directory**: Store backups in centralized location
+5. **Backup metadata**: Include generation parameters in backup
+6. **Version history**: Track multiple versions with rollback
+
+### Integration Points
+
+1. **WorkflowOrchestrator**: Auto-create backups before markdown modification
+2. **MarkdownParser**: Include backup info in parsed output
+3. **Image generators**: Auto-backup generated images
+4. **CLI tool**: Add `vf backup` commands for manual management
+
+---
+
+## Summary
+
+The backup system provides:
+
+✅ **Safety**: Never lose work, always reversible
+✅ **Transparency**: Automatic, no user action needed
+✅ **Control**: User decides when to approve/restore
+✅ **Persistence**: Survives session restarts
+✅ **Integrity**: MD5 verification ensures correctness
+✅ **Flexibility**: Enable/disable via environment variable
+
+**Configuration**: `VF_BACKUP_ENABLED=true` (default)
+**MCP Tools**: `approve_changes`, `restore_from_backups`, `list_backups`
+**Storage**: `.vf-bak` files alongside originals
+**State**: Tracked in `~/.visual-forge-mcp/state.json`
+
+---
+
+## References
+
+- **Implementation**: `src/backup/backup-manager.ts`
+- **Types**: `src/types/backup.ts`
+- **State**: `src/state/state-manager.ts`
+- **MCP Tools**: `src/server/mcp-server.ts`
+- **Tests**: `test/backup/` (coming soon)
+
+---
+
+**Last Updated**: 2026-01-13
+**Version**: 1.0.0
+**Status**: ✅ Implemented