@michelabboud/visual-forge-mcp 0.5.6 → 0.6.0

package/docs/guides/usage-examples.md

@@ -0,0 +1,101 @@
+# Example: Visual Forge MCP Usage
+
+This document demonstrates how to define images for generation using Visual Forge MCP.
+
+## Hero Image
+
+```image
+type: hero
+aspectRatio: 16:9
+section: Introduction
+prompt: Create a vibrant hero image showing a developer at a modern workspace with multiple monitors displaying code and documentation, futuristic tech aesthetic, clean and professional
+```
+
+## Architecture Diagram
+
+```image
+type: architecture
+aspectRatio: 16:9
+section: System Architecture
+prompt: System architecture diagram showing microservices architecture with API gateway at center, multiple service pods, message queue, database cluster, and caching layer, modern tech style with clean lines
+```
+
+## Flow Chart
+
+```image
+type: flowchart
+aspectRatio: 4:3
+section: User Authentication
+prompt: User authentication flow diagram starting from login page, through credential validation, 2FA verification, session creation, and ending at dashboard, include error paths and retry logic
+```
+
+## Technical Diagram
+
+```image
+type: diagram
+aspectRatio: 16:9
+section: Data Pipeline
+alt: Data pipeline architecture
+caption: End-to-end data processing pipeline
+prompt: Data pipeline diagram showing data ingestion from multiple sources, transformation stages, quality checks, and storage in data warehouse, with monitoring and alerting components
+```
+
+## Icon Set
+
+```image
+type: icon
+aspectRatio: 1:1
+section: Feature Icons
+prompt: Set of 4 modern minimalist icons representing: code, deployment, monitoring, and security, flat design with blue accent color
+```
+
+## Screenshots
+
+```image
+type: screenshot
+aspectRatio: 16:9
+section: User Interface
+prompt: Modern dashboard interface showing analytics charts, user activity metrics, and system health indicators, clean Material Design aesthetic
+```
+
+## Usage Instructions
+
+1. Save this file (or your own markdown files with image blocks)
+2. Start Visual Forge MCP server
+3. Use the MCP tools:
+
+```javascript
+// Parse this file
+parse_markdown({ filePaths: ["./example.md"] })
+
+// List what was parsed
+list_images()
+
+// Generate a single image
+generate_image({
+  imageId: "hero-img-01",
+  provider: "replicate"
+})
+
+// Or generate all images
+start_workflow({
+  mode: "bulk",
+  provider: "replicate",
+  concurrency: 3
+})
+
+// Monitor progress
+get_status()
+
+// Check costs
+get_cost_summary()
+```
+
+## Tips
+
+- Use descriptive prompts with specific details
+- Specify aspect ratio based on where image will be used
+- Include style guidance in prompt (flat, realistic, minimalist, etc.)
+- Consider cost vs quality tradeoffs when choosing provider
+- Start with no-cost providers (Gemini, HuggingFace) for testing
+- Use Replicate/FLUX for production (best value at $0.003/image)

package/docs/guides/vf-workflow.md

@@ -0,0 +1,112 @@
+# VF Parse Workflow - Quick Reference
+
+## Complete Steps (26 Total)
+
+### Phase 1: Session Setup & File Collection (Steps 1-6)
+1. User initiates VF Parse command
+2. Ask about Git workflow (branch/PR)
+3. Execute Git operations if requested
+4. Ask for additional files
+5. Continue file collection loop
+6. Display file list and get approval
+
+### Phase 2: Session Initialization & Context (Steps 7-10)
+7. Create session folder in `~/.visual-forge-mcp/sessions/[id]/`
+8. Ask for global theme/context/style
+9. Build global context pre-prompt
+10. Show theme/context for approval
+
+### Phase 3: File Processing & Placeholder Addition (Steps 11-14)
+11. Process each file sequentially
+12. Add image placeholders automatically with "Visual Forge Place Holder" title
+13. Update session tracking
+14. Parse all modified files
+
+### Phase 4: Image Generation (Steps 15-17)
+15. Ask for provider selection
+16. Start bulk generation with global context prepended
+17. Monitor generation progress
+
+### Phase 5: Automatic Document Update (Steps 18-19)
+18. Replace placeholders with image links automatically
+19. Update session tracking
+
+### Phase 6: Review & Refinement (Steps 20-23)
+20. Show completion summary
+21. Ask user to review
+22. Handle user feedback (regenerate/remove/replace)
+23. Continue review loop until satisfied
+
+### Phase 7: Finalization (Steps 24-26)
+24. Final approval
+25. Git operations (commit/PR if applicable)
+26. Close session and show summary
+
+## Session Recovery
+- All data saved to `~/.visual-forge-mcp/sessions/[session-id]/`
+- Can resume interrupted sessions
+- Ask user if they want to resume incomplete session
+
+## Key Files Created Per Session
+
+```
+~/.visual-forge-mcp/sessions/[session-id]/
+├── session-info.json          # Session state and tracking
+├── global-context.txt         # Global theme/style context
+└── [original-files-backup]/   # Optional: backup of originals
+```
+
+## Session Info JSON Structure
+
+```json
+{
+  "sessionId": "vf-session-20260113-123456",
+  "timestamp": "2026-01-13T12:34:56Z",
+  "files": ["README.md", "docs/guide.md"],
+  "gitBranch": "feature/visual-forge-images-20260113",
+  "status": "initializing|processing|parsing_complete|generating|generation_complete|completed",
+  "globalContext": "Professional technical documentation style...",
+  "provider": "gemini",
+  "images": [
+    {
+      "imageId": "README-img-01",
+      "file": "README.md",
+      "type": "hero",
+      "status": "placeholder_added|generating|generated|failed|inserted_into_document",
+      "addedAt": "2026-01-13T12:35:00Z",
+      "generatedAt": "2026-01-13T12:38:00Z",
+      "insertedAt": "2026-01-13T12:40:00Z",
+      "filepath": "generated-images/gemini/README-img-01.png",
+      "cost": 0.0
+    }
+  ],
+  "totalCost": 0.0,
+  "completedAt": "2026-01-13T12:45:00Z"
+}
+```
+
+## Important Principles
+
+✅ **Always add "Visual Forge Place Holder" title**
+✅ **Prepend global context to all image prompts**
+✅ **Automatically update documents after generation**
+✅ **Track everything in session-info.json**
+✅ **Enable session recovery if interrupted**
+✅ **Ask for approval at key milestones**
+✅ **Support user feedback loop for changes**
+
+## VF Command Aliases
+
+All these are equivalent:
+- `VF Parse [file]` ✅ DEFAULT
+- `Visual Parse [file]`
+- `Visual Forge Parse [file]`
+- `Visual Forge [file]`
+- `VF [file]`
+
+## Quick Commands
+
+- `VF status` - Check workflow status
+- `VF costs` - Show cost summary
+- `VF list` - List parsed images
+- `VF providers` - Show available providers

package/docs/guides/workflow-with-backups.md

@@ -0,0 +1,471 @@
+# Visual Forge MCP - Workflow with Backup System
+
+## Overview
+
+This document describes how the backup system integrates with the Visual Forge MCP workflow. The backup system provides automatic, transparent protection for your markdown files and generated images during the image generation workflow.
+
+## Workflow Phases
+
+### Phase 1: Session Start
+
+When you start a new Visual Forge session, the system automatically checks for pending backups from previous sessions.
+
+```typescript
+// User calls: vf_start_session
+{
+  files: ['docs/README.md'],
+  createBranch: true
+}
+
+// System Response:
+{
+  success: true,
+  sessionId: 'session-abc-123',
+  backupReminder: {
+    hasReminder: true,
+    message: '⏰ Reminder: You have pending backups from a previous session',
+    summary: '📸 Backup: backup-xyz-789\n   Created: 26 hours ago\n   Files: 2 markdown, 5 images',
+    actions: {
+      approve: 'Call approve_changes to keep modifications',
+      restore: 'Call restore_from_backups to undo all changes'
+    }
+  }
+}
+```
+
+**Backup Check Logic:**
+- If a backup is older than 24 hours, a reminder is shown
+- Users are informed about pending backups before starting new work
+- Users can approve or restore previous backups before continuing
+
+### Phase 2: Process Files
+
+Files are parsed and placeholders are added. No backup is created at this stage since markdown files aren't modified yet.
+
+```typescript
+// User calls: vf_process_files
+{
+  sessionId: 'session-abc-123'
+}
+
+// System Response:
+{
+  success: true,
+  filesProcessed: 1,
+  placeholdersAdded: 3,
+  imagesFound: 3
+}
+```
+
+### Phase 3: Generate Images
+
+This is where the backup system activates. After images are generated but **before** modifying markdown files:
+
+```typescript
+// User calls: vf_generate_session
+{
+  sessionId: 'session-abc-123',
+  provider: 'gemini',
+  mode: 'bulk'
+}
+
+// Internal Workflow:
+1. Generate all images (3 images created)
+2. 🔒 CREATE BACKUP (automatic, transparent)
+   - Backup markdown files
+   - Backup generated images
+   - Store backup metadata in state
+3. Replace placeholders with image references
+4. Update markdown files
+
+// System Response:
+{
+  success: true,
+  imagesGenerated: 3,
+  totalCost: 0.45,
+  filesUpdated: ['docs/README.md'],
+  backup: {
+    backupCreated: true,
+    backupId: 'backup-def-456',
+    filesBackedUp: 4,  // 1 markdown + 3 images
+    backupMessage: 'Files backed up. To keep changes: call approve_changes. To undo: call restore_from_backups.'
+  },
+  nextAction: 'Review images. To keep: call approve_changes. To undo: call restore_from_backups. Then call vf_finalize_session to commit.'
+}
+```
+
+**Backup Creation Details:**
+- **When**: After images are generated, before markdown modification
+- **What**: Markdown files + Generated images
+- **Where**: `.vf-bak` files alongside originals
+- **Integrity**: MD5 hash verification
+- **State**: Tracked in StateManager for persistence
+
+### Phase 4: Review and Decision
+
+Users review the generated images and decide whether to keep or undo the changes.
+
+#### Option A: Keep Changes (Approve)
+
+```typescript
+// User calls: approve_changes
+{}
+
+// System Response:
+{
+  success: true,
+  message: 'Changes approved successfully',
+  filesDeleted: 4,
+  backupId: 'backup-def-456'
+}
+
+// Result:
+- Backup files deleted (.vf-bak files removed)
+- Modified files kept
+- Backup moved to history
+```
+
+#### Option B: Undo Changes (Restore)
+
+```typescript
+// User calls: restore_from_backups
+{}
+
+// System Response:
+{
+  success: true,
+  message: 'All files restored successfully',
+  filesRestored: 4,
+  backupId: 'backup-def-456'
+}
+
+// Result:
+- Original files restored
+- Generated images removed
+- Backup files deleted
+- Backup moved to history
+```
+
+### Phase 5: Finalize Session
+
+After approving or restoring, finalize the session with git operations.
+
+```typescript
+// User calls: vf_finalize_session
+{
+  sessionId: 'session-abc-123',
+  commit: true,
+  createPR: true
+}
+
+// System Response:
+{
+  success: true,
+  summary: {
+    filesModified: ['docs/README.md'],
+    imagesGenerated: 3,
+    totalCost: 0.45,
+    prUrl: 'https://github.com/user/repo/pull/123'
+  }
+}
+```
+
+## Backup States and Transitions
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Backup Lifecycle                          │
+└─────────────────────────────────────────────────────────────┘
+
+NO BACKUP
+    ↓
+    ↓ (Images generated)
+    ↓
+BACKUP CREATED
+    ├─→ (approve_changes) ─→ APPROVED → History
+    └─→ (restore_from_backups) ─→ RESTORED → History
+```
+
+### Backup States
+
+| State | Description | Next Actions |
+|-------|-------------|--------------|
+| **No Backup** | No pending backups | Generate images |
+| **Backup Created** | Backup exists, pending decision | approve_changes OR restore_from_backups |
+| **Approved** | Changes kept, backup deleted | Archived in history |
+| **Restored** | Changes undone, backup deleted | Archived in history |
+
+## MCP Tools Reference
+
+### Check Backup Status
+
+```typescript
+// User calls: list_backups
+{}
+
+// Response with pending backup:
+{
+  hasPendingBackups: true,
+  current: {
+    id: 'backup-def-456',
+    createdAt: '2026-01-13T10:00:00Z',
+    markdownFiles: 1,
+    imageFiles: 3,
+    totalFiles: 4,
+    totalSize: 2048576,
+    needsReminder: false
+  },
+  summary: '📸 Backup: backup-def-456\n   Created: 2 hours ago\n   Files: 1 markdown, 3 images\n   Size: 2.00 MB',
+  actions: {
+    approve: 'Call approve_changes to keep modifications',
+    restore: 'Call restore_from_backups to undo all changes'
+  }
+}
+```
+
+### Approve Changes
+
+```typescript
+// User calls: approve_changes
+{}
+
+// Response:
+{
+  success: true,
+  message: 'Changes approved successfully',
+  filesDeleted: 4,
+  backupId: 'backup-def-456'
+}
+```
+
+### Restore from Backups
+
+```typescript
+// User calls: restore_from_backups
+{}
+
+// Response:
+{
+  success: true,
+  message: 'All files restored successfully',
+  filesRestored: 4,
+  backupId: 'backup-def-456'
+}
+```
+
+## Configuration
+
+### Enable/Disable Backups
+
+```bash
+# Enable backups (default)
+export VF_BACKUP_ENABLED=true
+
+# Disable backups
+export VF_BACKUP_ENABLED=false
+```
+
+When disabled:
+- No backup files created
+- Workflow continues normally
+- No backup-related messages in responses
+- Changes are immediately permanent
+
+### Backup File Location
+
+Backups are stored alongside original files with `.vf-bak` extension:
+
+```
+project/
+├── docs/
+│   ├── README.md              ← Modified file
+│   └── README.md.vf-bak       ← Backup (if exists)
+├── generated-images/
+│   ├── diagram-001.png        ← Generated image
+│   ├── diagram-001.png.vf-bak ← Backup (if exists)
+│   ├── diagram-002.png
+│   └── diagram-002.png.vf-bak
+```
+
+## Best Practices
+
+### For Users
+
+1. **Review Before Approving**: Always review generated images before calling `approve_changes`
+2. **Use Reminders**: Pay attention to 24-hour backup reminders
+3. **Clean Up**: Approve or restore backups promptly to avoid accumulation
+4. **Keep Enabled**: Leave backups enabled (default) for safety
+
+### For Developers
+
+1. **Check State**: Always check for pending backups in StateManager
+2. **Atomic Operations**: Ensure backup creation is atomic (all-or-nothing)
+3. **Error Handling**: Handle backup failures gracefully, don't block workflow
+4. **Log Operations**: Log backup creation, approval, and restoration for debugging
+
+## Error Scenarios
+
+### Backup Creation Fails
+
+```typescript
+{
+  success: true,  // Workflow continues
+  backup: {
+    backupCreated: false,
+    error: 'Failed to create backup: Permission denied'
+  },
+  // ... rest of response
+}
+```
+
+**Workflow continues normally** - backup failure doesn't block image generation.
+
+### Restore Fails (Partial)
+
+```typescript
+{
+  success: false,
+  filesRestored: 2,
+  errors: [
+    {
+      file: 'docs/GUIDE.md',
+      error: 'Backup file not found'
+    }
+  ]
+}
+```
+
+**Partial restore** - some files restored, errors reported for failures.
+
+## Integration Points
+
+### WorkflowTools Integration
+
+The backup system is integrated into `WorkflowTools` at these points:
+
+1. **handleStartSession()**: Checks for pending backups, shows reminders
+2. **handleGenerateSession()**: Creates backups before modifying markdown
+3. Response messages include backup information and next actions
+
+### StateManager Integration
+
+The backup system uses `StateManager` for persistence:
+
+- **Current Backup**: `stateManager.getCurrentBackup()`
+- **Set Backup**: `stateManager.setCurrentBackup(backupSet)`
+- **Clear Backup**: `stateManager.clearCurrentBackup(action)`
+- **Check Pending**: `stateManager.hasPendingBackups()`
+- **History**: `stateManager.getBackupHistory()`
+
+### BackupManager API
+
+Core backup operations:
+
+- **Create**: `backupManager.createBackup(markdownFiles, imageFiles)`
+- **Restore**: `backupManager.restoreFromBackup(backupSet)`
+- **Approve**: `backupManager.approveChanges(backupSet)`
+- **Check Reminder**: `backupManager.shouldRemind(backupSet)`
+- **Summary**: `backupManager.getBackupSummary(backupSet)`
+- **Verify**: `backupManager.verifyBackup(backupFile)`
+
+## Testing
+
+### Unit Tests
+
+Located in `test/backup/backup-manager.test.ts`:
+- Backup creation (24 tests)
+- Restore operations
+- Approval workflow
+- Reminder system
+- Integrity verification
+
+### Integration Tests
+
+Located in `test/workflow/workflow-backup-integration.test.ts`:
+- Session start with reminders (14 tests)
+- Backup creation during generation
+- State management
+- Full workflow lifecycle
+- Error handling
+
+### Running Tests
+
+```bash
+# All backup tests
+npm test -- test/backup/
+
+# Integration tests
+npm test -- test/workflow/workflow-backup-integration.test.ts
+
+# All tests
+npm test
+```
+
+## Troubleshooting
+
+### Issue: Backup files remain after approval
+
+**Check:**
+```bash
+# Find all backup files
+find . -name "*.vf-bak"
+
+# Manually remove
+find . -name "*.vf-bak" -delete
+```
+
+### Issue: Can't restore backup
+
+**Check:**
+```bash
+# Verify backup files exist
+ls -la docs/*.vf-bak
+
+# Check state
+cat ~/.visual-forge-mcp/state.json | grep -A 10 "backups"
+```
+
+### Issue: Backups not created
+
+**Check:**
+```bash
+# Verify enabled
+echo $VF_BACKUP_ENABLED  # Should be "true" or empty
+
+# Check logs
+tail -f ~/.visual-forge-mcp/logs/visual-forge.log | grep -i backup
+```
+
+## Summary
+
+The backup system provides:
+
+✅ **Automatic Protection**: Transparent backups without user action
+✅ **User Control**: Explicit approve/restore decisions
+✅ **Persistence**: Survives session restarts
+✅ **Reminders**: 24-hour notifications for pending backups
+✅ **Integrity**: MD5 verification ensures correctness
+✅ **Flexibility**: Enable/disable via environment variable
+
+**Default Behavior**: Backups ON, automatic creation, manual approval required
+
+**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`
+
+---
+
+**See Also:**
+- [Backup System Documentation](BACKUP_SYSTEM.md) - Complete backup system reference
+- [MCP Tools Reference](../README.md) - All available MCP tools
+- [Testing Guide](../TESTING_GUIDE.md) - Testing documentation
+
+---
+
+**Last Updated**: 2026-01-13
+**Version**: 1.0.0
+**Status**: ✅ Implemented and Tested