Merge pull request #115 from shinokada/feat/v3.8

feat: v3.8.0 Sync & Backup

* **New Features**
  * Rebranded "Gist Management" → "Sync & Backup" with guided export/restore and remote sync flows; checklist selections persist between runs.
  * Local ZIP export/restore with conflict detection, overwrite prompts, and atomic file operations.
  * Remote push/pull backup to GitHub Gists with in-place updates and deletion/tombstone handling.
  * New interactive checklist UI for multi-select sync choices.

* **Bug Fixes**
  * Improved terminal rendering to account for styled (ANSI) text; safer overwrite/conflict handling.

* **Tests**
  * Comprehensive unit tests for backups, gist sync, sync preferences, and checklist UI.

* **Documentation**
  * Added 3.8.0 changelog and updated README/docs for Sync & Backup.

Author: shinokada

CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to TERA will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.0] - 2026-03-10
+
+### ✨ Added
+
+#### Sync & Backup (menu renamed from "Gist Management")
+- **Export backup (zip)** — save all selected data to a local zip file; no GitHub token required
+- **Restore from backup (zip)** — restore selected categories from a local zip with overwrite warning
+- **Sync all data to Gist** — push selected categories to a dedicated secret `tera-data-backup` Gist
+- **Restore all data from Gist** — pull selected categories from the `tera-data-backup` Gist
+- **Category checklist** — shared checklist UI for all four operations; selections persist in `sync_prefs.json`
+- **Overwrite warning** — lists conflicting files before any restore, with Enter to proceed or Esc to cancel
+- **`sync_prefs.json`** — new file in the config directory that persists checklist selections across runs
+- **`tera-manifest.json`** sentinel in every backup Gist prevents false-positive matches on unrelated Gists
+
+#### Sync categories
+
+| Category                | Default |
+| ----------------------- | ------- |
+| Favorites (playlists)   | ✅ on    |
+| Settings (config.yaml)  | ✅ on    |
+| Ratings & votes         | ✅ on    |
+| Blocklist               | ✅ on    |
+| Station metadata & tags | ✅ on    |
+| Search history          | ❌ off   |
+
+### 🔒 Security
+- Reject path-traversal filenames in Gist restores (`fav--../../config.yaml` style attacks)
+- `FindBackupGist` errors on duplicate backup Gists instead of silently using the first match
+
+### 🐛 Fixed
+- Gist sync/restore actions now gate on `gistSyncMgr != nil` (previously showed misleading "token required" error when sync manager init failed)
+- `NewBackupManager` and `NewGistSyncManager` failures surfaced as startup warnings in the TUI
+- `SaveSyncPrefs` errors shown as non-blocking warnings instead of silently discarded
+- Empty checklist selection rejected before export/sync/restore flows begin
+- Removed redundant `GetGist` fetch in `Pull` (reuses the full Gist returned by `FindBackupGist`)
+
 ## [3.1.0]
 
 - OS keychain token storage with file-based fallback
@@ -227,3 +263,4 @@ Examples:
 ---
 
 [3.0.0]: https://github.com/shinokada/tera/releases/tag/v3.0.0
+[3.8.0]: https://github.com/shinokada/tera/releases/tag/v3.8.0

docs/README.md

@@ -12,7 +12,7 @@ A terminal-based internet radio player powered by [Radio Browser](https://www.ra
 - ⚡ **Quick Play** - Direct playback from main menu (shortcuts 10-99+)
 - 🔊 **Playback Control** - Play/pause with persistent status, adjust volume, and mute during playback
 - 🚫 **Block List** - Block unwanted stations from appearing in searches and auto-play
-- ☁️ **Gist Sync** - Backup and restore favorites via GitHub Gists
+- ☁️ **Sync & Backup** - Export/restore local zip backups and sync all data via GitHub Gists
 - 🗳️ **Voting** - Support your favorite stations on Radio Browser
 - 📊 **Most Played** - View your listening history sorted by play count, last played, or first played
 - 🎨 **Themes** - Choose from predefined themes or customize via unified config
@@ -134,7 +134,7 @@ tera
 # 7) Manage Lists        - Create/edit/delete favorite lists
 # 8) Block List          - Manage blocked stations
 # 9) I Feel Lucky        - Random station by keyword
-# 0) Gist Management     - Backup/restore via GitHub
+# 0) Sync & Backup       - Backup/restore data locally or via GitHub
 # -) Settings            - Configure TERA
 
 # Quick Play (from main menu):
@@ -671,7 +671,7 @@ You can edit this file directly or use the Settings menu.
 
 | Key      | Action                       |
 | -------- | ---------------------------- |
-| `0`      | Gist Management              |
+| `0`      | Sync & Backup                |
 | `1-9`    | Quick select menu item       |
 | `10-99+` | Quick play from My-favorites |
 | `-`      | Settings                     |
@@ -758,22 +758,54 @@ Results are sorted by **votes** (most popular first) and limited to 100 stations
 - Press `s` to add to another list
 - Press `v` to vote for the station
 
-## Gist Sync
+## Sync & Backup
 
-Backup and sync your favorite lists across devices using GitHub Gists.
+Back up and sync your data locally or across devices using zip archives and GitHub Gists.
+
+### Export Backup (zip)
+
+Save a local copy of your data with no GitHub account required.
+
+1. From the main menu press `0` → **Sync & Backup**
+2. Select **7. Export backup (zip)**
+3. Choose which categories to include (favorites, ratings, tags, etc.)
+4. Confirm the save path (default: `~/tera-backup-YYYY-MM-DD.zip`)
+
+### Restore from Backup (zip)
+
+1. Select **8. Restore from backup (zip)**
+2. Enter the path to your zip file
+3. Choose which categories to restore
+4. Confirm — you will be warned before any existing files are overwritten
+
+### Sync to Gist
+
+Push all selected data to a dedicated secret GitHub Gist (`tera-data-backup`).
 
 **Quick Setup:**
-1. Go to: Main Menu → 0) Gist Management → 6) Token Management
-2. Create a GitHub Personal Access Token (with `gist` scope only)
-3. Paste token in TERA
-4. Create your first gist backup!
+1. Go to **0) Sync & Backup → Token Management**
+2. Create a GitHub Personal Access Token with `gist` scope
+3. Paste the token in TERA
+4. Select **9. Sync all data to Gist** and choose categories
 
-**Features:**
-- Create secret or public gists
-- View your gist history
-- Recover favorites from any gist URL
-- Update gist descriptions
-- Delete old backups
+### Restore from Gist
+
+1. Select **10. Restore all data from Gist**
+2. TERA fetches the `tera-data-backup` Gist and shows available categories
+3. Choose what to restore — you will be warned before overwriting
+
+### Sync Categories
+
+| Category                | Default |
+| ----------------------- | ------- |
+| Favorites (playlists)   | ✅ on    |
+| Settings (config.yaml)  | ✅ on    |
+| Ratings & votes         | ✅ on    |
+| Blocklist               | ✅ on    |
+| Station metadata & tags | ✅ on    |
+| Search history          | ❌ off   |
+
+Category selections are saved in `sync_prefs.json` and reused on the next run.
 
 **Documentation:**
 - [Gist Setup Guide](/docs/GIST_SETUP.md) - Token setup and security

v3/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to TERA will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.0] - unreleased
+
+### Added (Phase 1 — Core Storage)
+- `storage.SyncPrefs` — per-category backup preferences persisted to `sync_prefs.json`; `LoadSyncPrefs()` / `SaveSyncPrefs()` with atomic write and defaults (search history off).
+- `storage.BackupManager` — zip-based export and restore using `archive/zip` (no new dependencies); `Export()`, `Restore()`, `ListArchiveCategories()`, `ConflictingFiles()`, `ResolveBackupPath()`.
+- `storage.RestoreConflictError` — typed error returned when a restore would overwrite existing files; carries the list of conflicting paths for the overwrite-warning UI.
+- `storage.GistSyncManager` — Gist-based push/pull of user data to a dedicated secret Gist (`tera-data-backup`); `Push()`, `Pull()`, `FindBackupGist()`, `AvailableCategories()`.
+- `gist.Client.UpdateGistFiles()` — new PATCH method to replace file contents of an existing Gist, needed by `GistSyncManager.Push()`.
+
+### Internal
+- `gist_filename` / `gistFilenameToRelPath` encode the config-relative path ↔ Gist filename mapping (e.g. `data/favorites/Jazz.json` ↔ `fav--Jazz.json`) since Gist filenames cannot contain `/`.
+- Unit tests: `sync_prefs_test.go`, `backup_test.go`, `gist_sync_test.go`.
+
+### Added (Phase 2 — UI Components)
+- `ui/components.ChecklistModel` — reusable bubbletea checklist component with cursor navigation (`↑↓`/`jk`), Space toggle, `a` toggle-all, Enter confirm, Esc/q cancel.
+- `ChecklistConfirmedMsg` / `ChecklistCancelledMsg` — typed tea messages emitted on confirm and cancel.
+- Unit tests: `checklist_test.go` (navigation, toggle, toggle-all, confirm/cancel, helpers, View).
+
+### Changed (Phase 3 — Gist Screen Integration)
+- `ui/gist.go`: Renamed screen title to `Sync & Backup`; added 8 new states for export/restore/sync flows; implemented export backup (checklist → path prompt → zip), restore from zip (path prompt → inspect → checklist → conflict check → overwrite warn/extract), sync to Gist (checklist → push), restore from Gist (fetch available categories → checklist → conflict check → overwrite warn/pull); overwrite warning prompt shared by zip and Gist flows; checklist selections persisted to `sync_prefs.json` on confirm.
+- `ui/app.go`: Menu label `Gist Management` → `Sync & Backup` via `syncBackupMenuLabel` constant.
+
+---
+
 ## [3.7.1] - 2026-03-09
 
 ### Fixed

v3/README.md

@@ -13,7 +13,7 @@ A terminal-based internet radio player powered by [Radio Browser](https://www.ra
 - 🕐 **Recently Played** - Last N stations shown below Quick Play Favorites in the main menu
 - 🔊 **Playback Control** - Play/pause with persistent status, adjust volume, and mute during playback
 - 🚫 **Block List** - Block unwanted stations from appearing in searches and auto-play
-- ☁️ **Gist Sync** - Backup and restore favorites via GitHub Gists
+- ☁️ **Sync & Backup** - Export/restore local zip backups and sync all data via GitHub Gists
 - 🗳️ **Voting** - Support your favorite stations on Radio Browser
 - 🎨 **Themes** - Choose from predefined themes or customize via YAML config
 - 💤 **Sleep Timer** - Set a timer to stop playback automatically
@@ -111,7 +111,7 @@ tera
 # 7) Manage Lists        - Create/edit/delete favorite lists
 # 8) Block List          - Manage blocked stations
 # 9) I Feel Lucky        - Random station by keyword
-# 0) Gist Management     - Backup/restore via GitHub
+# 0) Sync & Backup       - Backup/restore data locally or via GitHub
 # -) Settings            - Configure TERA
 
 # Quick Play (from main menu):
@@ -588,7 +588,7 @@ You can edit this file directly or use the Settings menu.
 
 | Key      | Action                       |
 | -------- | ---------------------------- |
-| `0`      | Gist Management              |
+| `0`      | Sync & Backup                |
 | `1-9`    | Quick select menu item       |
 | `10-99+` | Quick play from My-favorites / Recently Played |
 | `-`      | Settings                     |
@@ -682,22 +682,54 @@ Results are sorted by **votes** (most popular first) and limited to 100 stations
 - Press `s` to add to another list
 - Press `v` to vote for the station
 
-## Gist Sync
+## Sync & Backup
 
-Backup and sync your favorite lists across devices using GitHub Gists.
+Back up and sync your data locally or across devices using zip archives and GitHub Gists.
+
+### Export Backup (zip)
+
+Save a local copy of your data with no GitHub account required.
+
+1. From the main menu press `0` → **Sync & Backup**
+2. Select **7. Export backup (zip)**
+3. Choose which categories to include (favorites, ratings, tags, etc.)
+4. Confirm the save path (default: `~/tera-backup-YYYY-MM-DD.zip`)
+
+### Restore from Backup (zip)
+
+1. Select **8. Restore from backup (zip)**
+2. Enter the path to your zip file
+3. Choose which categories to restore
+4. Confirm — you will be warned before any existing files are overwritten
+
+### Sync to Gist
+
+Push all selected data to a dedicated secret GitHub Gist (`tera-data-backup`).
 
 **Quick Setup:**
-1. Go to: Main Menu → 0) Gist Management → 6) Token Management
-2. Create a GitHub Personal Access Token (with `gist` scope only)
-3. Paste token in TERA
-4. Create your first gist backup!
+1. Go to **0) Sync & Backup → Token Management**
+2. Create a GitHub Personal Access Token with `gist` scope
+3. Paste the token in TERA
+4. Select **9. Sync all data to Gist** and choose categories
 
-**Features:**
-- Create secret or public gists
-- View your gist history
-- Recover favorites from any gist URL
-- Update gist descriptions
-- Delete old backups
+### Restore from Gist
+
+1. Select **10. Restore all data from Gist**
+2. TERA fetches the `tera-data-backup` Gist and shows available categories
+3. Choose what to restore — you will be warned before overwriting
+
+### Sync Categories
+
+| Category                | Default |
+| ----------------------- | ------- |
+| Favorites (playlists)   | ✅ on    |
+| Settings (config.yaml)  | ✅ on    |
+| Ratings & votes         | ✅ on    |
+| Blocklist               | ✅ on    |
+| Station metadata & tags | ✅ on    |
+| Search history          | ❌ off   |
+
+Category selections are saved in `sync_prefs.json` and reused on the next run.
 
 **Documentation:**
 - [Gist Setup Guide](GIST_SETUP.md) - Token setup and security

v3/internal/gist/client.go

@@ -48,20 +48,37 @@ type GistFile struct {
 	RawURL   string `json:"raw_url,omitempty"`
 }
 
-// CreateGist creates a new gist with the provided files
-// If public is true, the gist will be publicly visible; otherwise it will be secret
-func (c *Client) CreateGist(description string, files map[string]string, public bool) (*Gist, error) {
-	gistFiles := make(map[string]GistFile)
+// GistFileUpdate wraps the content field for PATCH requests.
+// Deletion is represented by a nil file entry in the parent files map;
+// a non-nil GistFileUpdate sets or replaces the file content.
+type GistFileUpdate struct {
+	Content *string `json:"content"`
+}
+
+// gistFileCreate is the per-file payload for POST /gists.
+// Content is a plain string without omitempty so that empty files are
+// serialised as {"content":""} rather than being silently dropped.
+type gistFileCreate struct {
+	Content string `json:"content"`
+}
+
+// CreateGist creates a new gist with the provided files.
+// If public is true, the gist will be publicly visible; otherwise it will be
+// secret. Each map value is a pointer: nil entries are skipped (deletion has
+// no meaning on create), non-nil pointers set the file content.
+func (c *Client) CreateGist(description string, files map[string]*string, public bool) (*Gist, error) {
+	gistFiles := make(map[string]gistFileCreate)
 	for filename, content := range files {
-		gistFiles[filename] = GistFile{
-			Content: content,
+		if content == nil {
+			continue // nothing to create for a nil entry
 		}
+		gistFiles[filename] = gistFileCreate{Content: *content}
 	}
 
 	payload := struct {
-		Description string              `json:"description"`
-		Public      bool                `json:"public"`
-		Files       map[string]GistFile `json:"files"`
+		Description string                     `json:"description"`
+		Public      bool                       `json:"public"`
+		Files       map[string]gistFileCreate  `json:"files"`
 	}{
 		Description: description,
 		Public:      public,
@@ -86,19 +103,28 @@ func (c *Client) CreateGist(description string, files map[string]string, public
 	return &gist, nil
 }
 
-// ListGists lists all gists for the authenticated user
+// ListGists lists all gists for the authenticated user, paginating through
+// all pages so callers see the complete set regardless of account size.
 func (c *Client) ListGists() ([]*Gist, error) {
-	req, err := http.NewRequest("GET", c.baseURL+"/gists", nil)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-
-	var gists []*Gist
-	if err := c.do(req, &gists); err != nil {
-		return nil, err
+	var all []*Gist
+	page := 1
+	for {
+		url := fmt.Sprintf("%s/gists?per_page=100&page=%d", c.baseURL, page)
+		req, err := http.NewRequest("GET", url, nil)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create request: %w", err)
+		}
+		var pageGists []*Gist
+		if err := c.do(req, &pageGists); err != nil {
+			return nil, err
+		}
+		all = append(all, pageGists...)
+		if len(pageGists) < 100 {
+			break // last page
+		}
+		page++
 	}
-
-	return gists, nil
+	return all, nil
 }
 
 // UpdateGist updates the description of an existing gist
@@ -122,6 +148,39 @@ func (c *Client) UpdateGist(gistID, description string) error {
 	return c.do(req, nil)
 }
 
+// UpdateGistFiles updates or replaces the files of an existing gist.
+// Each key in files is the filename; the value controls the operation:
+//   - nil pointer → delete the file (sends null per the GitHub API)
+//   - non-nil pointer → set or replace content, including empty string
+func (c *Client) UpdateGistFiles(gistID string, files map[string]*string) error {
+	gistFiles := make(map[string]*GistFileUpdate)
+	for filename, content := range files {
+		if content == nil {
+			gistFiles[filename] = nil // marshals to null → deletes the file
+		} else {
+			gistFiles[filename] = &GistFileUpdate{Content: content}
+		}
+	}
+
+	payload := struct {
+		Files map[string]*GistFileUpdate `json:"files"`
+	}{
+		Files: gistFiles,
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("failed to marshal update payload: %w", err)
+	}
+
+	req, err := http.NewRequest("PATCH", fmt.Sprintf("%s/gists/%s", c.baseURL, gistID), bytes.NewBuffer(body))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	return c.do(req, nil)
+}
+
 // DeleteGist deletes a gist
 func (c *Client) DeleteGist(gistID string) error {
 	req, err := http.NewRequest("DELETE", fmt.Sprintf("%s/gists/%s", c.baseURL, gistID), nil)