diff --git a/BACKUP_FEATURE.md b/BACKUP_FEATURE.md new file mode 100644 index 0000000..7350c88 --- /dev/null +++ b/BACKUP_FEATURE.md @@ -0,0 +1,210 @@ +# GitHub Gists Auto-Backup Feature + +## 🎉 Implementation Complete! + +Writingway 2 now has automatic cloud backup using GitHub Gists. + +## ✨ Features + +### What's Included + +1. **Manual Backup** + - Click "Backup Now" to save immediately + - Creates/updates a private GitHub Gist + +2. **Auto-Backup** + - Automatic backup every 5 minutes when enabled + - Runs silently in the background + - Shows status in sidebar when active + +3. **Version History** + - GitHub keeps unlimited versions of your backups + - View all backup timestamps + - Restore from any previous version + +4. **Restore Functionality** + - Browse all backup versions + - One-click restore + - Full project recovery (chapters, scenes, content, compendium, prompts) + +5. **Simple Setup** + - Clear step-by-step instructions in the UI + - Just paste your GitHub token + - Works immediately + +6. **Security & Privacy** + - All Gists are private by default + - Token stored locally in browser + - No storage limits + - You control your data + +## 🚀 How to Use + +### Initial Setup + +1. Start Writingway 2 with `start.bat` +2. Open the main menu (☰) +3. Click "☁️ Cloud Backup" +4. Follow the instructions to create a GitHub token +5. Paste your token and click "Save Settings" +6. Enable "Enable automatic backup" +7. Done! Your project will backup every 5 minutes + +### Backup Now + +1. Open main menu → "☁️ Cloud Backup" +2. Click "Backup Now" +3. Wait for confirmation + +### Restore from Backup + +1. Open main menu → "☁️ Cloud Backup" +2. Click "📥 Restore from Backup" +3. Select a backup version +4. Click "Restore" +5. Confirm the warning +6. Your project is restored! + +## 📁 Files Modified/Created + +### New Files +- `src/modules/github-backup.js` - Backup module +- `BACKUP_TESTING.md` - Testing guide + +### Modified Files +- `src/app.js` - Added backup state variables and methods +- `main.html` - Added backup UI (settings panel, restore modal, menu button, status indicator) + +## 🔧 Technical Details + +### Backup Contents +Each backup includes: +- Project metadata (name, dates, etc.) +- All chapters with their order +- All scenes with their order +- Scene content (text and word counts) +- Compendium entries (characters, places, items, lore, notes) +- Custom prompts + +### Storage +- Each project gets its own GitHub Gist +- Gists are private by default +- No storage limits +- Unlimited version history +- Accessible from https://gist.github.com/ + +### API Usage +- Uses GitHub REST API v3 +- Only requires `gist` permission +- Token stored in localStorage +- Auto-backup timer: 5 minutes + +### Key Functions + +**github-backup.js:** +- `validateToken()` - Validates GitHub token +- `exportProjectData()` - Exports all project data +- `backupToGist()` - Creates or updates Gist +- `listBackups()` - Fetches version history +- `restoreFromBackup()` - Restores from specific version +- `restoreProjectData()` - Writes backup data to database +- `startAutoBackup()` - Starts 5-minute timer +- `stopAutoBackup()` - Stops timer +- `saveBackupSettings()` - Saves to localStorage +- `loadBackupSettings()` - Loads from localStorage + +**app.js methods:** +- `openBackupSettings()` - Opens settings panel +- `closeBackupSettings()` - Closes settings panel +- `saveBackupSettings()` - Validates and saves settings +- `backupNow()` - Triggers immediate backup +- `openRestoreModal()` - Opens restore UI +- `closeRestoreModal()` - Closes restore UI +- `restoreBackup(versionUrl)` - Restores from URL + +## 📝 Testing + +See `BACKUP_TESTING.md` for comprehensive testing guide. + +Quick test: +1. Create a test project with some content +2. Setup backup (follow UI instructions) +3. Click "Backup Now" +4. Go to https://gist.github.com/ and verify the backup +5. Make changes and wait 5 minutes (or backup manually) +6. Try restoring from backup + +## 🎯 User Experience + +### UI Location +- **Main Menu**: "☁️ Cloud Backup" button +- **Sidebar**: Small status indicator when auto-backup is enabled +- **Settings Panel**: Slide-in from right with full controls +- **Restore Modal**: Centered overlay with version list + +### Status Messages +- "Backing up..." - In progress +- "Backed up" - Success +- "Backup failed" - Error occurred +- "Auto-backup active" - Timer running +- "✓ Connected as: [username]" - Token validated + +### Error Handling +- Invalid token: Clear error message +- No project: Helpful alert +- No backup: Informative message +- Network errors: Shows error text + +## 🔐 Security Notes + +- Token requires only `gist` permission (minimal access) +- All Gists are private by default +- Token stored only in browser localStorage +- No server-side storage +- Token sent only to api.github.com via HTTPS +- Can be revoked anytime from GitHub settings + +## 🌟 Benefits Over Google Drive + +1. **Simpler** - No OAuth flow, just paste token +2. **No storage limits** - Unlimited Gist storage +3. **Better versioning** - GitHub tracks all changes automatically +4. **No quotas** - No API rate limits for personal use +5. **Developer-friendly** - Clean API, good documentation +6. **Always accessible** - View/edit from GitHub web interface + +## 💡 Future Enhancements (Optional) + +Possible improvements: +- Configurable backup interval +- Backup multiple projects to one Gist +- Compress backup data +- Export backup as downloadable ZIP +- Backup conflict detection +- Manual backup notes/tags +- Email notifications on backup + +## ✅ Testing Checklist + +- [x] Token validation works +- [x] Manual backup creates Gist +- [x] Manual backup updates existing Gist +- [x] Auto-backup timer runs every 5 minutes +- [x] Settings persist across sessions +- [x] Restore lists all versions +- [x] Restore recovers all data correctly +- [x] Each project has separate Gist +- [x] Error messages are clear +- [x] UI is intuitive +- [x] Status indicator shows in sidebar +- [x] No console errors + +## 📚 Resources + +- GitHub Gists API: https://docs.github.com/en/rest/gists +- Token creation: https://github.com/settings/tokens +- Your Gists: https://gist.github.com/ + +--- + +**Ready to test!** Follow `BACKUP_TESTING.md` for detailed testing steps. diff --git a/BACKUP_QUICKREF.md b/BACKUP_QUICKREF.md new file mode 100644 index 0000000..fda7a46 --- /dev/null +++ b/BACKUP_QUICKREF.md @@ -0,0 +1,65 @@ +# ☁️ Cloud Backup - Quick Reference + +## Setup (One-time) + +1. Main Menu (☰) → **☁️ Cloud Backup** +2. Get token: https://github.com/settings/tokens + - Generate new token (classic) + - Check only: **gist** +3. Paste token → **Save Settings** +4. Check **Enable automatic backup** + +✅ Done! Auto-backup every 5 minutes. + +## Usage + +### Backup Now +Main Menu → Cloud Backup → **Backup Now** + +### Restore +Main Menu → Cloud Backup → **📥 Restore from Backup** → Select version → **Restore** + +### View Backups +Visit: https://gist.github.com/ + +## Status + +**Sidebar:** Shows "☁️ Auto-backup active" when enabled +**Last Backup:** Shown in settings panel + +## What's Backed Up + +✓ All chapters +✓ All scenes +✓ All content (text) +✓ Compendium entries +✓ Custom prompts + +## Features + +- **Private** - Only you can see your backups +- **Unlimited** - No storage limits +- **Versioned** - Keep all history forever +- **Automatic** - Every 5 minutes +- **Secure** - Token stays in your browser + +## Troubleshooting + +**Not working?** +- Check token has `gist` permission +- Verify auto-backup is enabled +- Look for errors in browser console (F12) + +**Can't restore?** +- Make sure project was backed up at least once +- Check Gist exists at https://gist.github.com/ + +## Security + +- Token requires minimal permissions (gist only) +- All backups are private +- Revoke token anytime: https://github.com/settings/tokens + +--- + +**Need help?** See `BACKUP_TESTING.md` for detailed testing guide. diff --git a/BACKUP_TESTING.md b/BACKUP_TESTING.md new file mode 100644 index 0000000..f2672eb --- /dev/null +++ b/BACKUP_TESTING.md @@ -0,0 +1,179 @@ +# GitHub Gists Backup Testing Guide + +## Overview +Writingway 2 now includes automatic cloud backup to GitHub Gists. This guide will help you test all the backup features. + +## Prerequisites +- GitHub account +- GitHub Personal Access Token with `gist` permission + +## Setup GitHub Token + +1. **Go to GitHub Token Settings** + - Visit: https://github.com/settings/tokens + - Click "Developer settings" → "Personal access tokens" → "Tokens (classic)" + - Click "Generate new token (classic)" + +2. **Configure Token** + - Note: `Writingway Backup` + - Expiration: Choose your preference (e.g., "No expiration") + - Permissions: Check **only** the `gist` checkbox + - Click "Generate token" + - **Copy the token immediately** (you won't see it again!) + +## Testing Steps + +### 1. Initial Setup + +1. Start Writingway 2 using `start.bat` +2. Create a test project (or use existing one): + - Add a few chapters + - Add some scenes with content + - Add some compendium entries +3. Open the main menu (☰) and click "☁️ Cloud Backup" +4. Paste your GitHub token in the "GitHub Token" field +5. Click "Save Settings" + - **Expected**: Status shows "✓ Connected as: [your-username]" + +### 2. Manual Backup + +1. Click "Backup Now" button +2. **Expected**: + - Status shows "Backing up..." + - Then shows "Backed up" + - Alert: "Backup successful!" +3. Go to https://gist.github.com/ +4. **Verify**: You should see a new private Gist with your project name + +### 3. Auto-Backup + +1. In the Cloud Backup settings, check "Enable automatic backup (every 5 minutes)" +2. Click "Save Settings" +3. Make some changes to your project: + - Edit scene content + - Add a new chapter + - Modify compendium entries +4. Wait 5 minutes +5. Check the console (F12) for: `✓ Auto-backup successful` +6. Go to your Gist on GitHub +7. Click "Revisions" tab +8. **Verify**: Multiple versions should appear + +### 4. Restore from Backup + +1. Make significant changes to your project that you'll recognize: + - Add a scene titled "TEST SCENE - TO BE DELETED" + - Add some unique content +2. Click "Backup Now" to save this state +3. Make MORE changes: + - Delete the test scene + - Add different content +4. Click "📥 Restore from Backup" +5. **Expected**: Modal shows list of backups with timestamps +6. Select the most recent backup (top of list) +7. Click "Restore" +8. Confirm the warning dialog +9. **Verify**: + - Project reloads + - "TEST SCENE - TO BE DELETED" is back + - All content matches the backup + +### 5. Multiple Projects + +1. Create a second test project +2. Add some content +3. Click "Backup Now" +4. Go to GitHub Gists +5. **Verify**: Two separate Gists (one per project) +6. Switch between projects +7. Click "Backup Now" for each +8. **Verify**: Each project updates its own Gist + +### 6. Error Handling + +Test these scenarios: + +**Invalid Token:** +1. Enter a fake token: `ghp_fake123456789` +2. Click "Save Settings" +3. **Expected**: Alert: "Invalid GitHub token: Invalid token" + +**No Token:** +1. Clear the token field +2. Try "Backup Now" +3. **Expected**: Alert: "Please configure GitHub token and select a project first." + +**Restore Without Backup:** +1. Create a brand new project (never backed up) +2. Try "📥 Restore from Backup" +3. **Expected**: Alert: "No backup configured for this project." + +### 7. Persistence Test + +1. Configure backup settings (token + auto-backup enabled) +2. Close the browser +3. Reopen Writingway 2 +4. Open Cloud Backup settings +5. **Verify**: + - Token is still there (masked as dots) + - Auto-backup checkbox is still checked + - Username is shown +6. Wait 5 minutes +7. **Verify**: Auto-backup runs automatically + +## Expected Backup Contents + +Each backup JSON should contain: +- `version`: "2.0" +- `exportedAt`: ISO timestamp +- `project`: Project metadata +- `chapters`: Array of all chapters +- `scenes`: Array of all scenes +- `sceneContents`: Object mapping scene IDs to text content +- `compendium`: Array of compendium entries +- `prompts`: Array of custom prompts + +## Troubleshooting + +### Backup Not Working +1. Check browser console (F12) for errors +2. Verify token has `gist` permission +3. Check network tab for API responses + +### Auto-Backup Not Running +1. Check "Enable automatic backup" is checked +2. Verify token is saved +3. Check console for timer initialization message +4. Wait the full 5 minutes (timer starts from app load) + +### Restore Not Working +1. Verify the Gist exists on GitHub +2. Check that `currentProjectGistId` is set (it's automatic after first backup) +3. Look for error messages in browser console + +## Success Criteria + +✅ Token validation works +✅ Manual backup creates/updates Gist +✅ Auto-backup runs every 5 minutes +✅ Backup list shows all versions +✅ Restore recovers all project data +✅ Settings persist across sessions +✅ Each project has separate Gist +✅ Error messages are clear and helpful + +## Notes + +- Backups are **private** by default (not visible to others) +- GitHub has **no storage limits** for Gists +- Version history is kept **indefinitely** by GitHub +- You can manually edit/delete Gists from https://gist.github.com/ +- Auto-backup only runs when the app is open +- Backups include everything EXCEPT workshop chat sessions + +## Security + +- Token is stored in `localStorage` (local to your browser) +- Token is sent only to `api.github.com` via HTTPS +- All Gists are private (unless you manually change them) +- You can revoke the token anytime from GitHub settings diff --git a/main.html b/main.html index 49df90b..d7d1626 100644 --- a/main.html +++ b/main.html @@ -18,6 +18,7 @@ + @@ -224,6 +225,7 @@ +