final feature set

tasks/episode-downloads/14-download-storage-structure.md

@@ -0,0 +1,46 @@
+# 14. Define Download Storage Structure
+
+meta:
+  id: episode-downloads-14
+  feature: episode-downloads
+  priority: P2
+  depends_on: []
+  tags: [storage, types, data-model]
+
+objective:
+- Define data structures for downloaded episodes
+- Create download state tracking
+- Design download history and metadata storage
+
+deliverables:
+- DownloadedEpisode type definition
+- Download state interface
+- Storage schema for download metadata
+
+steps:
+1. Add DownloadedEpisode type to types/episode.ts
+2. Define download state structure (status, progress, timestamp)
+3. Create download metadata interface
+4. Add download-related fields to Feed type
+5. Design database-like storage structure
+
+tests:
+- Unit: Test type definitions
+- Integration: Test storage schema
+- Validation: Verify structure supports all download scenarios
+
+acceptance_criteria:
+- DownloadedEpisode type properly defines download metadata
+- Download state interface tracks all necessary information
+- Storage schema supports history and progress tracking
+
+validation:
+- Review type definitions for completeness
+- Verify storage structure can hold all download data
+- Test with mock download scenarios
+
+notes:
+- Add fields: status (downloading, completed, failed), progress (0-100), filePath, downloadedAt
+- Include download speed and estimated time remaining
+- Store download history with timestamps
+- Consider adding resume capability

tasks/episode-downloads/15-episode-download-utility.md

@@ -0,0 +1,47 @@
+# 15. Create Episode Download Utility
+
+meta:
+  id: episode-downloads-15
+  feature: episode-downloads
+  priority: P2
+  depends_on: [episode-downloads-14]
+  tags: [downloads, utilities, file-io]
+
+objective:
+- Implement episode download functionality
+- Download audio files from episode URLs
+- Handle download errors and edge cases
+
+deliverables:
+- Download utility function
+- File download handler
+- Error handling for download failures
+
+steps:
+1. Create `src/utils/episode-downloader.ts`
+2. Implement download function using Bun.file() or fetch
+3. Add progress tracking during download
+4. Handle download cancellation
+5. Add error handling for network and file system errors
+
+tests:
+- Unit: Test download function with mock URLs
+- Integration: Test with real audio file URLs
+- Error handling: Test download failure scenarios
+
+acceptance_criteria:
+- Episodes can be downloaded successfully
+- Download progress is tracked
+- Errors are handled gracefully
+
+validation:
+- Download test episode from real podcast
+- Verify file is saved correctly
+- Check download progress tracking
+
+notes:
+- Use Bun's built-in file download capabilities
+- Support resuming interrupted downloads
+- Handle large files with streaming
+- Add download speed tracking
+- Consider download location in downloadPath setting

tasks/episode-downloads/16-download-progress-tracking.md

@@ -0,0 +1,47 @@
+# 16. Implement Download Progress Tracking
+
+meta:
+  id: episode-downloads-16
+  feature: episode-downloads
+  priority: P2
+  depends_on: [episode-downloads-15]
+  tags: [progress, state-management, downloads]
+
+objective:
+- Track download progress for each episode
+- Update download state in real-time
+- Store download progress in persistent storage
+
+deliverables:
+- Download progress state in app store
+- Progress update utility
+- Integration with download utility
+
+steps:
+1. Add download state to app store
+2. Update progress during download
+3. Save progress to persistent storage
+4. Handle download completion
+5. Test progress tracking accuracy
+
+tests:
+- Unit: Test progress update logic
+- Integration: Test progress tracking with download
+- Persistence: Verify progress saved and restored
+
+acceptance_criteria:
+- Download progress is tracked accurately
+- Progress updates in real-time
+- Progress persists across app restarts
+
+validation:
+- Download a large file and watch progress
+- Verify progress updates at intervals
+- Restart app and verify progress restored
+
+notes:
+- Use existing progress store for episode playback
+- Create separate download progress store
+- Update progress every 1-2 seconds
+- Handle download cancellation by resetting progress
+- Store progress in XDG_CONFIG_HOME directory

tasks/episode-downloads/17-download-ui-component.md

@@ -0,0 +1,47 @@
+# 17. Add Download Status in Episode List
+
+meta:
+  id: episode-downloads-17
+  feature: episode-downloads
+  priority: P2
+  depends_on: [episode-downloads-16]
+  tags: [ui, downloads, display]
+
+objective:
+- Display download status for episodes
+- Add download button to episode list
+- Show download progress visually
+
+deliverables:
+- Download status indicator component
+- Download button in episode list
+- Progress bar for downloading episodes
+
+steps:
+1. Add download status field to EpisodeListItem
+2. Create download button in MyShowsPage episodes panel
+3. Display download status (none, queued, downloading, completed, failed)
+4. Add download progress bar for downloading episodes
+5. Test download status display
+
+tests:
+- Integration: Test download status display
+- Visual: Verify download button and progress bar
+- UX: Test download status changes
+
+acceptance_criteria:
+- Download status is visible in episode list
+- Download button is accessible
+- Progress bar shows download progress
+
+validation:
+- View episode list with download button
+- Start download and watch status change
+- Verify progress bar updates
+
+notes:
+- Reuse existing episode list UI from MyShowsPage
+- Add download icon button next to episode title
+- Show status text: "DL", "DWN", "DONE", "ERR"
+- Use existing progress bar component for download progress
+- Position download button in episode header

tasks/episode-downloads/18-auto-download-settings.md

@@ -0,0 +1,48 @@
+# 18. Implement Per-Feed Auto-Download Settings
+
+meta:
+  id: episode-downloads-18
+  feature: episode-downloads
+  priority: P2
+  depends_on: [episode-downloads-17]
+  tags: [settings, automation, downloads]
+
+objective:
+- Add per-feed auto-download settings
+- Configure number of episodes to auto-download per feed
+- Enable/disable auto-download per feed
+
+deliverables:
+- Auto-download settings in feed store
+- Settings UI for per-feed configuration
+- Auto-download trigger logic
+
+steps:
+1. Add autoDownload field to Feed type
+2. Add autoDownloadCount field to Feed type
+3. Add settings UI in FeedPage or MyShowsPage
+4. Implement auto-download trigger logic
+5. Test auto-download functionality
+
+tests:
+- Unit: Test auto-download trigger logic
+- Integration: Test with multiple feeds
+- Edge case: Test with feeds having fewer episodes
+
+acceptance_criteria:
+- Auto-download settings are configurable per feed
+- Settings are saved to persistent storage
+- Auto-download works correctly when enabled
+
+validation:
+- Configure auto-download for a feed
+- Subscribe to new episodes and verify auto-download
+- Test with multiple feeds
+
+notes:
+- Add settings in FeedPage or MyShowsPage
+- Default: autoDownload = false, autoDownloadCount = 0
+- Only download newest episodes (by pubDate)
+- Respect MAX_EPISODES_REFRESH limit
+- Add settings in feed detail or feed list
+- Consider adding "auto-download all new episodes" setting

tasks/episode-downloads/19-download-queue-management.md

@@ -0,0 +1,48 @@
+# 19. Create Download Queue Management
+
+meta:
+  id: episode-downloads-19
+  feature: episode-downloads
+  priority: P3
+  depends_on: [episode-downloads-18]
+  tags: [queue, downloads, management]
+
+objective:
+- Manage download queue for multiple episodes
+- Handle concurrent downloads
+- Provide queue UI for managing downloads
+
+deliverables:
+- Download queue data structure
+- Download queue manager
+- Download queue UI
+
+steps:
+1. Create download queue data structure
+2. Implement download queue manager (add, remove, process)
+3. Handle concurrent downloads (limit to 1-2 at a time)
+4. Create download queue UI component
+5. Test queue management
+
+tests:
+- Unit: Test queue management logic
+- Integration: Test with multiple downloads
+- Edge case: Test queue with 50+ episodes
+
+acceptance_criteria:
+- Download queue manages multiple downloads
+- Concurrent downloads are limited
+- Queue UI shows download status
+
+validation:
+- Add 10 episodes to download queue
+- Verify queue processes sequentially
+- Check queue UI displays correctly
+
+notes:
+- Use queue data structure (array of episodes)
+- Limit concurrent downloads to 2 for performance
+- Add queue UI in Settings or separate tab
+- Show queue in SettingsScreen or new Downloads tab
+- Allow removing items from queue
+- Add pause/resume for downloads

tasks/episode-downloads/README.md

@@ -0,0 +1,26 @@
+# Episode Downloads
+
+Objective: Add per-episode download and per-feed auto-download settings
+
+Status legend: [ ] todo, [~] in-progress, [x] done
+
+Tasks
+- [ ] 14 — Define download storage structure → `14-download-storage-structure.md`
+- [ ] 15 — Create episode download utility → `15-episode-download-utility.md`
+- [ ] 16 — Implement download progress tracking → `16-download-progress-tracking.md`
+- [ ] 17 — Add download status in episode list → `17-download-ui-component.md`
+- [ ] 18 — Implement per-feed auto-download settings → `18-auto-download-settings.md`
+- [ ] 19 — Create download queue management → `19-download-queue-management.md`
+
+Dependencies
+- 14 -> 15
+- 15 -> 16
+- 16 -> 17
+- 17 -> 18
+- 18 -> 19
+
+Exit criteria
+- Episodes can be downloaded individually
+- Per-feed auto-download settings are configurable
+- Download progress is tracked and displayed
+- Download queue can be managed