final feature set

tasks/config-persistence/23-config-directory-setup.md

@@ -0,0 +1,50 @@
+# 23. Implement XDG_CONFIG_HOME Directory Setup
+
+meta:
+  id: config-persistence-23
+  feature: config-persistence
+  priority: P1
+  depends_on: []
+  tags: [configuration, file-system, directory-setup]
+
+objective:
+- Implement XDG_CONFIG_HOME directory detection and creation
+- Create application-specific config directory
+- Handle XDG_CONFIG_HOME environment variable
+- Provide fallback to ~/.config if XDG_CONFIG_HOME not set
+
+deliverables:
+- Config directory detection utility
+- Directory creation logic
+- Environment variable handling
+
+steps:
+1. Create `src/utils/config-dir.ts`
+2. Implement XDG_CONFIG_HOME detection
+3. Create fallback to HOME/.config
+4. Create application-specific directory (podcast-tui-app)
+5. Add directory creation with error handling
+
+tests:
+- Unit: Test XDG_CONFIG_HOME detection
+- Unit: Test config directory creation
+- Manual: Verify directory exists at expected path
+
+acceptance_criteria:
+- Config directory is created at correct path
+- XDG_CONFIG_HOME is respected if set
+- Falls back to ~/.config if XDG_CONFIG_HOME not set
+- Directory is created with correct permissions
+
+validation:
+- Run app and check config directory exists
+- Test with XDG_CONFIG_HOME=/custom/path
+- Test with XDG_CONFIG_HOME not set
+- Verify directory is created in both cases
+
+notes:
+- XDG_CONFIG_HOME default: ~/.config
+- App name from package.json: podcast-tui-app
+- Use Bun.file() and file operations for directory creation
+- Handle permission errors gracefully
+- Use mkdir -p for recursive creation

tasks/config-persistence/24-feeds-persistence-refactor.md

@@ -0,0 +1,51 @@
+# 24. Refactor Feeds Persistence to JSON File
+
+meta:
+  id: config-persistence-24
+  feature: config-persistence
+  priority: P1
+  depends_on: [config-persistence-23]
+  tags: [persistence, feeds, file-io]
+
+objective:
+- Move feeds persistence from localStorage to JSON file
+- Load feeds from XDG_CONFIG_HOME directory
+- Save feeds to JSON file
+- Maintain backward compatibility
+
+deliverables:
+- Feeds JSON file I/O functions
+- Updated feed store persistence
+- Migration from localStorage
+
+steps:
+1. Create `src/utils/feeds-persistence.ts`
+2. Implement loadFeedsFromFile() function
+3. Implement saveFeedsToFile() function
+4. Update feed store to use file-based persistence
+5. Add migration from localStorage to file
+
+tests:
+- Unit: Test file I/O functions
+- Integration: Test feed persistence with file
+- Migration: Test migration from localStorage
+
+acceptance_criteria:
+- Feeds are loaded from JSON file
+- Feeds are saved to JSON file
+- Backward compatibility maintained
+
+validation:
+- Start app with no config file
+- Subscribe to feeds
+- Verify feeds saved to file
+- Restart app and verify feeds loaded
+- Test migration from localStorage
+
+notes:
+- File path: XDG_CONFIG_HOME/podcast-tui-app/feeds.json
+- Use JSON.stringify/parse for serialization
+- Handle file not found (empty initial load)
+- Handle file write errors
+- Add timestamp to file for versioning
+- Maintain Feed type structure

tasks/config-persistence/25-theme-persistence-refactor.md

@@ -0,0 +1,52 @@
+# 25. Refactor Theme Persistence to JSON File
+
+meta:
+  id: config-persistence-25
+  feature: config-persistence
+  priority: P1
+  depends_on: [config-persistence-23]
+  tags: [persistence, themes, file-io]
+
+objective:
+- Move theme persistence from localStorage to JSON file
+- Load custom themes from XDG_CONFIG_HOME directory
+- Save custom themes to JSON file
+- Maintain backward compatibility
+
+deliverables:
+- Themes JSON file I/O functions
+- Updated theme persistence
+- Migration from localStorage
+
+steps:
+1. Create `src/utils/themes-persistence.ts`
+2. Implement loadThemesFromFile() function
+3. Implement saveThemesToFile() function
+4. Update theme store to use file-based persistence
+5. Add migration from localStorage to file
+
+tests:
+- Unit: Test file I/O functions
+- Integration: Test theme persistence with file
+- Migration: Test migration from localStorage
+
+acceptance_criteria:
+- Custom themes are loaded from JSON file
+- Custom themes are saved to JSON file
+- Backward compatibility maintained
+
+validation:
+- Start app with no theme file
+- Load custom theme
+- Verify theme saved to file
+- Restart app and verify theme loaded
+- Test migration from localStorage
+
+notes:
+- File path: XDG_CONFIG_HOME/podcast-tui-app/themes.json
+- Use JSON.stringify/parse for serialization
+- Handle file not found (use default themes)
+- Handle file write errors
+- Add timestamp to file for versioning
+- Maintain theme type structure
+- Include all theme files in directory

tasks/config-persistence/26-config-file-validation.md

@@ -0,0 +1,51 @@
+# 26. Add Config File Validation and Migration
+
+meta:
+  id: config-persistence-26
+  feature: config-persistence
+  priority: P1
+  depends_on: [config-persistence-24, config-persistence-25]
+  tags: [validation, migration, data-integrity]
+
+objective:
+- Validate config file structure and data integrity
+- Migrate data from localStorage to file
+- Provide migration on first run
+- Handle config file corruption
+
+deliverables:
+- Config file validation function
+- Migration utility from localStorage
+- Error handling for corrupted files
+
+steps:
+1. Create config file schema validation
+2. Implement migration from localStorage to file
+3. Add config file backup before migration
+4. Handle corrupted JSON files
+5. Test migration scenarios
+
+tests:
+- Unit: Test validation function
+- Integration: Test migration from localStorage
+- Error: Test corrupted file handling
+
+acceptance_criteria:
+- Config files are validated before use
+- Migration from localStorage works seamlessly
+- Corrupted files are handled gracefully
+
+validation:
+- Start app with localStorage data
+- Verify migration to file
+- Corrupt file and verify handling
+- Test migration on app restart
+
+notes:
+- Validate Feed type structure
+- Validate theme structure
+- Create backup before migration
+- Log migration events
+- Provide error messages for corrupted files
+- Add config file versioning
+- Test with both new and old data formats

tasks/config-persistence/27-config-file-backup.md

@@ -0,0 +1,50 @@
+# 27. Implement Config File Backup on Update
+
+meta:
+  id: config-persistence-27
+  feature: config-persistence
+  priority: P2
+  depends_on: [config-persistence-26]
+  tags: [backup, data-safety, migration]
+
+objective:
+- Create backups of config files before updates
+- Handle config file changes during app updates
+- Provide rollback capability if needed
+
+deliverables:
+- Config backup utility
+- Backup on config changes
+- Config version history
+
+steps:
+1. Create config backup function
+2. Implement backup on config save
+3. Add config version history management
+4. Test backup and restore scenarios
+5. Add config file version display
+
+tests:
+- Unit: Test backup function
+- Integration: Test backup on config save
+- Manual: Test restore from backup
+
+acceptance_criteria:
+- Config files are backed up before updates
+- Backup preserves data integrity
+- Config version history is maintained
+
+validation:
+- Make config changes
+- Verify backup created
+- Restart app and check backup
+- Test restore from backup
+
+notes:
+- Backup file naming: feeds.json.backup, themes.json.backup
+- Keep last N backups (e.g., 5)
+- Backup timestamp in filename
+- Use atomic file operations
+- Test with large config files
+- Add config file size tracking
+- Consider automatic cleanup of old backups

tasks/config-persistence/README.md

@@ -0,0 +1,25 @@
+# Config Persistence to XDG_CONFIG_HOME
+
+Objective: Move feeds and themes persistence from localStorage to XDG_CONFIG_HOME directory
+
+Status legend: [ ] todo, [~] in-progress, [x] done
+
+Tasks
+- [ ] 23 — Implement XDG_CONFIG_HOME directory setup → `23-config-directory-setup.md`
+- [ ] 24 — Refactor feeds persistence to JSON file → `24-feeds-persistence-refactor.md`
+- [ ] 25 — Refactor theme persistence to JSON file → `25-theme-persistence-refactor.md`
+- [ ] 26 — Add config file validation and migration → `26-config-file-validation.md`
+- [ ] 27 — Implement config file backup on update → `27-config-file-backup.md`
+
+Dependencies
+- 23 -> 24
+- 23 -> 25
+- 24 -> 26
+- 25 -> 26
+- 26 -> 27
+
+Exit criteria
+- Feeds are persisted to XDG_CONFIG_HOME/podcast-tui-app/feeds.json
+- Themes are persisted to XDG_CONFIG_HOME/podcast-tui-app/themes.json
+- Config file validation ensures data integrity
+- Migration from localStorage works seamlessly