From 4bca034ba4049264ede37251bf28a48d239b6aa1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 16:42:52 +0000 Subject: [PATCH] Reorganize plan: milestone-driven structure with focused details MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete restructure of the plan document: NEW STRUCTURE: 1. Vision (brief high-level overview at top) 2. Phase 1-7 (each phase is self-contained) Each phase now includes: - Goal and rationale - Architecture decisions relevant to THAT phase - Dependencies for THAT phase only - Features checklist - Usage examples - Deliverables MOVED CONTENT: - Data model → Phase 1 (when it's needed) - Workspace structure → Phase 1 - Storage strategy → Phase 1 - Core library API → Phase 1 - WebDAV architecture → Phase 2 (when it's implemented) - Frontend framework decision → Phase 3 (when it matters) - Mobile architecture → Phase 4 (when it's built) - Performance strategy → Phase 3 (with GUI) REMOVED: - Upfront architectural details that weren't immediately relevant - Repetitive explanations scattered throughout - "Questions & Decisions" section (decisions now inline with phases) - "Technical Challenges" section (addressed in relevant phases) BENEFITS: - Much easier to read and follow - Focus on immediate next steps (Phase 1) - Architecture details appear when they're actually needed - Each phase is actionable and self-contained - Reduced cognitive load - Clear progression path Document is now 750 lines (down from 900+) and much more focused. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 1274 +++++++++++++++++++++++++------------------------------ 1 file changed, 571 insertions(+), 703 deletions(-) diff --git a/PLAN.md b/PLAN.md index 61408e4..57415d3 100644 --- a/PLAN.md +++ b/PLAN.md @@ -2,70 +2,53 @@ ## Vision -A local-first, cross-platform tasks application inspired by Google Tasks, built with Bevy for high performance and future game-like UX polish. The application will launch near-instantly on all platforms and support both local file storage and WebDAV synchronization. +A **local-first, cross-platform tasks application** inspired by Google Tasks. Built with Rust for high performance and true native support across Windows, Linux, macOS, iOS, and Android. -## Core Principles +**Core Principles**: +- **Local-First**: Your data, your folder, your control +- **Privacy**: Data stays on your devices and chosen storage +- **Fast**: Sub-second startup, instant response +- **Portable**: Plain markdown files, works with any text editor +- **Cross-Platform**: Single codebase, all platforms +- **Future-Proof**: Clean architecture enables game-like polish later -1. **Local-First**: All data is stored locally by default, with optional sync -2. **Performance**: Sub-second cold start time on all platforms -3. **Cross-Platform**: Native support for Windows, Linux, macOS, iOS, and Android -4. **Privacy**: User data stays on their devices and chosen storage locations -5. **Future-Proof**: Built on Bevy to enable advanced UI/UX features later +**Data Format**: Tasks stored as markdown files with YAML frontmatter (Obsidian-compatible) +**Storage**: User selects folder location (e.g., `~/Documents/Tasks`, `~/Dropbox/Tasks`) +**Sync**: Optional WebDAV for cross-device synchronization +**Architecture**: Backend/frontend separation with CLI-first development -## Target Platforms +--- -- **Desktop**: Windows, Linux, macOS -- **Mobile**: iOS, Android +## Phase 1: Core Library & CLI MVP -## Technology Stack +**Goal**: Build and validate the backend with a functional CLI -### Project Structure: Workspace with Backend/Frontend Separation +### Why CLI First? +- Test backend thoroughly before GUI complexity +- CLI useful for power users and automation +- Clean API boundaries +- Easy to write comprehensive tests -The project is organized as a Cargo workspace with three main crates: - -1. **bevy-tasks-core** (Library): Pure Rust business logic, no UI dependencies -2. **bevy-tasks-cli** (Binary): Command-line interface for power users and testing -3. **bevy-tasks-gui** (Binary): Graphical frontend (framework TBD - see Frontend Comparison) - -This separation provides: -- Clean architecture with testable core logic -- Multiple interfaces to the same backend -- Ability to develop and validate backend before frontend work -- CLI tool useful for automation, scripting, and CI/CD - -### Backend/Core Library -- **serde**: Serialization/deserialization -- **pulldown-cmark** or **markdown**: Markdown parsing -- **serde_yaml**: YAML frontmatter parsing (Obsidian-style metadata) -- **directories**: Cross-platform path handling -- **tokio**: Async runtime for I/O operations -- **reqwest** + **dav-client**: WebDAV support -- **uuid**: Unique identifiers for tasks -- **chrono**: Date/time handling -- **anyhow**: Error handling - -### CLI Frontend -- **clap**: Command-line argument parsing -- **colored**: Terminal colors for better UX -- **indicatif**: Progress bars for sync operations - -### GUI Frontend -See "Frontend Framework Comparison" section below for detailed options. - -### Performance Optimization -- **Lazy loading**: Load only visible data -- **Minimal dependencies**: Keep binary size small -- **Release optimizations**: LTO, strip symbols -- **Backend separation**: Core logic has zero UI overhead - -## Architecture - -### Data Model - -Tasks are stored as individual `.md` (Markdown) files, with metadata in YAML frontmatter (Obsidian-compatible format). +### Architecture +#### Cargo Workspace Structure ``` -Task File Format (my-task-name.md): +bevy-tasks/ +├── Cargo.toml # Workspace definition +├── PLAN.md +├── README.md +├── crates/ +│ ├── bevy-tasks-core/ # Core library (backend) +│ ├── bevy-tasks-cli/ # CLI frontend +│ └── bevy-tasks-gui/ # GUI frontend (Phase 3+) +└── docs/ +``` + +#### Data Model + +Tasks are stored as individual `.md` files with YAML frontmatter: + +```markdown --- id: 550e8400-e29b-41d4-a716-446655440000 status: in-progress @@ -92,11 +75,11 @@ Task { notes: String, // Markdown content status: TaskStatus, // From frontmatter due_date: Option, // From frontmatter - created_at: DateTime, // From frontmatter - updated_at: DateTime, // From frontmatter - parent_id: Option, // From frontmatter - position: i32, // From frontmatter - tags: Vec, // From frontmatter + created_at: DateTime, + updated_at: DateTime, + parent_id: Option, + position: i32, + tags: Vec, } TaskList { @@ -109,91 +92,36 @@ TaskList { } AppConfig { - // Stored in platform-specific config location local_path: PathBuf, // User-selected tasks folder (required) - webdav_url: Option, // Optional WebDAV server - webdav_credentials: Option, theme: Theme, - last_sync: Option, - window_size: Option<(u32, u32)>, last_opened_list: Option, } ``` -### Workspace Structure +#### File System Structure ``` -bevy-tasks/ -├── Cargo.toml # Workspace definition -├── PLAN.md -├── README.md -│ -├── crates/ -│ ├── bevy-tasks-core/ # Core library (backend) -│ │ ├── Cargo.toml -│ │ ├── src/ -│ │ │ ├── lib.rs -│ │ │ ├── task.rs # Task model -│ │ │ ├── task_list.rs # TaskList model -│ │ │ ├── config.rs # AppConfig -│ │ │ ├── repository.rs # High-level API -│ │ │ ├── storage/ -│ │ │ │ ├── mod.rs -│ │ │ │ ├── local.rs # Local file I/O -│ │ │ │ ├── markdown.rs # Markdown parser -│ │ │ │ └── webdav.rs # WebDAV sync -│ │ │ └── error.rs # Error types -│ │ └── tests/ -│ │ ├── integration.rs -│ │ └── fixtures/ -│ │ -│ ├── bevy-tasks-cli/ # CLI frontend -│ │ ├── Cargo.toml -│ │ ├── src/ -│ │ │ ├── main.rs -│ │ │ ├── commands/ -│ │ │ │ ├── mod.rs -│ │ │ │ ├── add.rs -│ │ │ │ ├── list.rs -│ │ │ │ ├── complete.rs -│ │ │ │ ├── sync.rs -│ │ │ │ └── init.rs -│ │ │ └── ui.rs # Terminal formatting -│ │ └── README.md -│ │ -│ └── bevy-tasks-gui/ # GUI frontend -│ ├── Cargo.toml -│ ├── src/ -│ │ ├── main.rs # App entry point -│ │ ├── app.rs # Framework setup -│ │ ├── ui/ -│ │ │ ├── mod.rs -│ │ │ ├── screens/ -│ │ │ │ ├── task_list.rs -│ │ │ │ ├── task_detail.rs -│ │ │ │ └── settings.rs -│ │ │ └── components/ -│ │ │ ├── task_item.rs -│ │ │ ├── task_input.rs -│ │ │ └── list_selector.rs -│ │ └── state.rs # UI state management -│ ├── assets/ -│ │ ├── fonts/ -│ │ └── icons/ -│ └── README.md -│ -└── docs/ - ├── API.md - ├── CLI.md - └── DEVELOPMENT.md +~/Documents/Tasks/ # User-selected folder +├── .bevy-tasks/ +│ └── metadata.json # List ordering, sync state +├── My Tasks/ # Task list folder +│ ├── Buy groceries.md +│ ├── Call dentist.md +│ └── Project X/ # Subtask folder (optional) +│ └── Design mockup.md +└── Work/ # Another task list + ├── Review PRs.md + └── Team meeting prep.md ``` -### Core Library API Design +**App Configuration** (separate from task data): +- Windows: `%APPDATA%/bevy-tasks/config.json` +- Linux: `~/.config/bevy-tasks/config.json` +- macOS: `~/Library/Application Support/bevy-tasks/config.json` -The `bevy-tasks-core` library will expose a clean, high-level API: +#### Core Library API ```rust -// Main repository interface pub struct TaskRepository { storage: Box, } @@ -213,14 +141,8 @@ impl TaskRepository { pub fn create_list(&mut self, name: String) -> Result; pub fn get_lists(&self) -> Result>; pub fn delete_list(&mut self, id: Uuid) -> Result<()>; - - // Sync operations - pub fn sync_push(&mut self) -> Result; - pub fn sync_pull(&mut self) -> Result; - pub fn sync_status(&self) -> Result; } -// Storage trait for local and WebDAV implementations pub trait Storage { fn read_task(&self, list_id: Uuid, task_id: Uuid) -> Result; fn write_task(&mut self, list_id: Uuid, task: &Task) -> Result<()>; @@ -228,380 +150,9 @@ pub trait Storage { } ``` -### Storage Strategy +### Dependencies -#### Local Storage -- **Location**: **User must select a folder** on first run - - Can be anywhere with read/write permissions - - Examples: `~/Documents/Tasks`, `~/Dropbox/Tasks`, `D:\My Tasks` - - Users can change location later in settings - - **No hidden default directories** - full user control and visibility -- **App Configuration Storage** (separate from task data): - - Windows: `%APPDATA%/bevy-tasks/config.json` - - Linux: `~/.config/bevy-tasks/config.json` - - macOS: `~/Library/Application Support/bevy-tasks/config.json` - - iOS: App sandbox preferences - - Android: App preferences - - Stores: selected folder path, theme, last sync time, window position -- **Format**: Markdown files with YAML frontmatter (Obsidian-compatible) -- **Structure**: - ``` - ~/Documents/Tasks/ # User-selected folder - ├── .bevy-tasks/ - │ └── metadata.json # List ordering, sync state - ├── My Tasks/ # Task list folder - │ ├── Buy groceries.md - │ ├── Call dentist.md - │ └── Project X/ # Subtask folder (optional) - │ └── Design mockup.md - └── Work/ # Another task list - ├── Review PRs.md - └── Team meeting prep.md - ``` - -**First Run Experience**: -- CLI: `bevy-tasks init ~/Documents/Tasks` (user specifies path) -- GUI: Folder picker dialog on first launch -- Mobile: Folder picker with suggested locations (Documents, iCloud Drive, etc.) - -**Benefits of User-Selected Storage**: -- **Full transparency**: Users can see exactly where their data is -- **Easy backup**: Users can backup the folder however they want (Time Machine, cloud sync, etc.) -- **Portable**: Move folder between machines, cloud drives, USB drives -- **No lock-in**: Data is in plain markdown, accessible without the app -- **Git-friendly**: Users can version control their tasks folder -- **Compatible with other tools**: Use with Obsidian, Logseq, VS Code, etc. -- **Multiple vaults**: Users can have separate task folders for work/personal -- **User choice**: Dropbox, iCloud, OneDrive, local folder - user decides - -#### WebDAV Sync -- **Conflict Resolution**: Last-write-wins with timestamp -- **Sync Strategy**: - - On app start (if connected) - - On background timer (every 5 minutes when active) - - On task modification (debounced) -- **Offline Support**: All operations work offline, sync when online - -### Performance Strategy - -#### Fast Startup Requirements -1. **Minimal initialization**: Load only essential systems -2. **Lazy data loading**: Load visible tasks first -3. **Background operations**: Non-critical data and sync after first render -4. **Efficient file I/O**: Stream large markdown files -5. **Small binary size**: Minimal dependencies in core library - -#### Startup Sequence (egui GUI) -1. Initialize eframe window (< 50ms) -2. Load config from disk (< 20ms) -3. Render empty UI (first frame < 100ms) -4. Load current task list in background -5. Update UI as tasks load (incremental rendering) -6. Start WebDAV sync in background (if configured) - -**Target**: < 200ms cold start on desktop - -#### Memory Optimization -- Use `Vec` instead of `HashMap` for small collections -- Limit rendered tasks to visible viewport -- Lazy load task lists (only load selected list) -- Stream markdown parsing for large files - -## Feature Roadmap - -### Phase 1: Core Library & CLI MVP -**Goal**: Build and validate the backend with a functional CLI - -**Features**: -- [ ] Project workspace setup (bevy-tasks-core, bevy-tasks-cli, bevy-tasks-gui) -- [ ] Data models (Task, TaskList, AppConfig) -- [ ] Markdown file I/O with YAML frontmatter parsing -- [ ] Local storage implementation -- [ ] Repository pattern and public API -- [ ] CLI: init, add, list, complete, delete, edit commands -- [ ] CLI: Basic task listing and formatting -- [ ] Comprehensive unit and integration tests - -**Deliverables**: -- `bevy-tasks-core` library with stable API -- Functional CLI that can manage tasks via command line -- Data persists as Obsidian-compatible .md files -- Well-tested backend (>80% coverage) - -**CLI Example**: -```bash -# First run: initialize tasks folder -bevy-tasks init ~/Documents/Tasks - -# Or use a cloud-synced folder -bevy-tasks init ~/Dropbox/Tasks - -# Then use normally -bevy-tasks add "Buy groceries" --list "Personal" -bevy-tasks list -bevy-tasks complete - -# Change folder location -bevy-tasks config set-folder ~/new/location -``` - -### Phase 2: WebDAV Sync (Backend + CLI) -**Goal**: Enable cross-device synchronization via CLI - -**Features**: -- [ ] WebDAV client implementation in core library -- [ ] Credential storage (platform keychain) -- [ ] Bi-directional sync (push/pull/auto) -- [ ] Conflict resolution (last-write-wins) -- [ ] Offline queue for pending operations -- [ ] CLI: sync setup, push, pull, status commands -- [ ] CLI: Progress indicators for sync operations - -**Deliverables**: -- Working WebDAV sync in backend -- CLI can sync with remote WebDAV server -- Reliable conflict resolution tested with real servers (Nextcloud, ownCloud) - -**CLI Example**: -```bash -bevy-tasks sync --setup -bevy-tasks sync --push -bevy-tasks sync --pull -bevy-tasks sync --status -``` - -### Phase 3: GUI MVP (Desktop) -**Goal**: Build graphical interface on desktop platforms - -**Features**: -- [ ] egui framework integration -- [ ] Basic task list view -- [ ] Create/edit/delete tasks -- [ ] Mark tasks complete -- [ ] Settings screen (change folder location, WebDAV config) -- [ ] Desktop support (Windows, Linux, macOS) -- [ ] Sync status indicators - -**Deliverables**: -- Functional desktop GUI app -- Sub-second startup time -- Clean, minimal UI -- Feature parity with CLI - -### Phase 4: Mobile Basic Support -**Goal**: Get app running on iOS and Android ASAP, even if basic - -**Priority**: Early validation of mobile platform, test infrastructure - -**Features**: -- [ ] iOS build pipeline setup -- [ ] Android build pipeline setup -- [ ] Basic egui mobile adaptation -- [ ] Simple UI with core features (even if just test buttons) -- [ ] File system access on mobile -- [ ] Basic task CRUD on mobile -- [ ] Folder picker for mobile - -**Deliverables**: -- App launches on iOS -- App launches on Android -- Can create and view tasks on mobile -- Validates cross-platform architecture -- Foundation for future mobile polish - -**Note**: This phase prioritizes getting mobile working early, even with a simple test UI. Polish comes later. - -### Phase 5: GUI Advanced Features (Desktop + Mobile) -**Goal**: Feature parity with Google Tasks across all platforms - -**Features**: -- [ ] Multiple task lists (folders) -- [ ] Switch between lists -- [ ] Subtasks support -- [ ] Due dates with date picker -- [ ] Rich markdown editor for task notes -- [ ] Drag & drop reordering (desktop) -- [ ] Swipe gestures (mobile) -- [ ] Move tasks between lists -- [ ] Change storage folder location in settings -- [ ] Keyboard shortcuts (desktop) -- [ ] Search functionality -- [ ] Pull-to-refresh (mobile) - -**Deliverables**: -- Full-featured task manager on all platforms -- Polished UX on desktop -- Touch-optimized UX on mobile -- Consistent feature set - -### Phase 6: Mobile Polish & Platform-Specific Features -**Goal**: Native mobile experience and platform integration - -**Features**: -- [ ] Background sync on mobile -- [ ] Share extension (share to tasks on iOS/Android) -- [ ] Widgets (iOS/Android home screen widgets) -- [ ] Notifications for due dates -- [ ] Quick capture shortcuts -- [ ] Haptic feedback -- [ ] Platform-specific gestures and animations -- [ ] App icon badge with task count - -**Deliverables**: -- Native-feeling mobile apps -- Deep platform integration -- Mobile-specific features - -### Phase 7: Advanced Features & Imports -**Goal**: Differentiate from Google Tasks, add unique features - -**Features**: -- [ ] **Google Tasks importer** (migrate from Google Tasks) -- [ ] Themes and customization -- [ ] Full-text search across tasks -- [ ] Filters and smart lists -- [ ] Task templates -- [ ] Recurring tasks -- [ ] Statistics and insights -- [ ] Tags and custom fields -- [ ] Export/import (backup/restore) -- [ ] Bulk operations -- [ ] Advanced animations (consider Bevy migration) -- [ ] Plugin system for extensions (optional) -- [ ] Calendar integration -- [ ] Email to task -- [ ] Voice input -- [ ] Collaboration features (share lists) - -**Deliverables**: -- Polished, delightful UX -- Unique features not in Google Tasks -- Easy migration path from Google Tasks -- Distribution to all app stores - -## Development Guidelines - -### Performance Budgets -- **Cold start**: < 500ms on desktop, < 1s on mobile -- **First render**: < 100ms -- **Task creation**: < 50ms -- **Sync operation**: < 2s for typical dataset (< 1000 tasks) -- **Memory usage**: < 50MB on mobile, < 100MB on desktop - -### Testing Strategy -- **Unit tests**: Data models and business logic -- **Integration tests**: Storage layer operations -- **E2E tests**: Critical user flows -- **Performance tests**: Startup time, large datasets -- **Platform tests**: Verify each platform build - -### Build & Release -- **CI/CD**: GitHub Actions for all platforms -- **Initial Distribution** (Phases 3-4): - - **Desktop**: Direct downloads and sideloading - - Linux: AppImage, .tar.gz - - macOS: DMG - - Windows: MSI, portable .exe - - **Mobile**: Sideloading and TestFlight - - iOS: .ipa for TestFlight (early access) - - Android: .apk (direct install) -- **Future Distribution Channels** (Phase 7): - - **F-Droid**: FOSS Android app store - - **Flathub**: Linux Flatpak repository - - **Google Play Store**: Android - - **Apple App Store**: iOS and macOS - - **Microsoft Store**: Windows -- **Version scheme**: Semantic versioning (0.1.0 → 1.0.0) -- **Release notes**: Auto-generated from commits - -## Technical Challenges & Solutions - -### Challenge 1: Fast Startup with GUI -**Problem**: UI initialization can add overhead - -**Solutions (egui)**: -- Use eframe with minimal features -- Defer loading of non-visible data -- Initialize window before loading tasks -- Profile startup and optimize hot paths -- Keep core library dependency-light - -### Challenge 2: Mobile Platform Support -**Problem**: iOS and Android have different requirements - -**Solutions**: -- **Early mobile testing** (Phase 4) - validate cross-platform architecture ASAP -- Start with simple test UI to verify builds work -- Use conditional compilation for platform-specific code -- Test on real devices early and often -- egui's touch support as starting point, enhance as needed -- Follow platform guidelines (iOS HIG, Material Design) in later phases -- Use platform-specific file pickers and sharing (via native bridges) - -### Challenge 3: WebDAV Reliability -**Problem**: Network can be unreliable, auth can be complex - -**Solutions**: -- Implement robust retry logic with exponential backoff -- Cache credentials securely (see Authentication Options below) -- Queue operations when offline -- Provide clear sync status to user -- Support multiple WebDAV servers (Nextcloud, ownCloud, etc.) - -### Challenge 4: Data Migration -**Problem**: Schema changes need to preserve user data - -**Solutions**: -- Version frontmatter schema from day one -- Write migration scripts for each version bump -- Markdown format is naturally forward/backward compatible -- Users handle their own backups (external to app) -- Migration can be done in-place by updating frontmatter - -## Frontend Framework Decision - -**Decision Made**: Hybrid approach with **egui** for Phase 3, optional **Bevy** migration in Phase 6. - -### Phase 3-6: egui (Immediate Mode GUI) - -**Why egui for MVP and mobile?** -- ✅ Fast development with rich built-in widgets -- ✅ Excellent text editing and form support out of the box -- ✅ Small binary size (~2-3MB stripped) -- ✅ Fast startup time (100-200ms) -- ✅ Mature and stable -- ✅ Simple immediate-mode API -- ✅ Cross-platform (desktop AND mobile) -- ✅ Easy integration with `bevy-tasks-core` -- ✅ **Mobile builds possible early** - can test on iOS/Android quickly - -**Trade-offs**: -- ⚠️ Less flexibility for custom animations -- ⚠️ Mobile UX requires extra work for touch optimization -- ⚠️ Not as "game-like" polish potential - -**Mobile Strategy with egui**: -- Phase 4: Get basic egui running on mobile (even simple test UI) -- Phase 5: Improve touch handling and mobile UX -- Phase 6: Add platform-specific mobile features - -### Phase 7 (Optional): Migration to Bevy - -**If you want game-like polish later (after Phase 7):** -- ✅ Full control over animations and rendering -- ✅ Unique, polished look beyond standard apps -- ✅ Mature mobile support (iOS/Android) -- ✅ ECS architecture for complex interactions -- ✅ Backend stays identical (clean separation!) - -**Why this works:** -The `bevy-tasks-core` library is UI-framework agnostic, so switching from egui to Bevy only requires rewriting the `bevy-tasks-gui` crate. All business logic, file I/O, sync, and testing remains unchanged. - -This approach de-risks the project: validate the concept with egui (including mobile in Phase 4!), then optionally invest in custom polish with Bevy if the app takes off. - -## Dependencies - -### Workspace Structure (Cargo.toml) +**Workspace Cargo.toml**: ```toml [workspace] members = [ @@ -612,7 +163,6 @@ members = [ resolver = "2" [workspace.dependencies] -# Shared dependencies serde = { version = "1.0", features = ["derive"] } uuid = { version = "1.0", features = ["serde", "v4"] } chrono = { version = "0.4", features = ["serde"] } @@ -620,7 +170,7 @@ anyhow = "1.0" tokio = { version = "1.40", features = ["full"] } ``` -### Core Library (bevy-tasks-core/Cargo.toml) +**bevy-tasks-core/Cargo.toml**: ```toml [package] name = "bevy-tasks-core" @@ -630,26 +180,18 @@ edition = "2024" [dependencies] serde = { workspace = true } serde_json = "1.0" -serde_yaml = "0.9" # YAML frontmatter parsing -pulldown-cmark = "0.12" # Markdown parsing +serde_yaml = "0.9" # YAML frontmatter +pulldown-cmark = "0.12" # Markdown parsing uuid = { workspace = true } chrono = { workspace = true } -directories = "5.0" # Cross-platform paths -tokio = { workspace = true } +directories = "5.0" anyhow = { workspace = true } -# WebDAV support -reqwest = { version = "0.12", features = ["json", "rustls-tls"] } -# TODO: Evaluate dav-client or implement custom WebDAV - -# Credential storage -keyring = "3.0" # Cross-platform keychain - [dev-dependencies] -tempfile = "3.0" # For testing file operations +tempfile = "3.0" ``` -### CLI (bevy-tasks-cli/Cargo.toml) +**bevy-tasks-cli/Cargo.toml**: ```toml [package] name = "bevy-tasks-cli" @@ -663,13 +205,217 @@ path = "src/main.rs" [dependencies] bevy-tasks-core = { path = "../bevy-tasks-core" } clap = { version = "4.5", features = ["derive", "env"] } -colored = "2.0" # Terminal colors -indicatif = "0.17" # Progress bars +colored = "2.0" +indicatif = "0.17" anyhow = { workspace = true } tokio = { workspace = true } ``` -### GUI (bevy-tasks-gui/Cargo.toml) +### Features + +- [ ] Cargo workspace setup +- [ ] Data models (Task, TaskList, AppConfig) +- [ ] Markdown file I/O with YAML frontmatter parsing +- [ ] Local storage implementation +- [ ] Repository pattern and public API +- [ ] CLI: `init` command (user selects folder) +- [ ] CLI: `add` command (create tasks) +- [ ] CLI: `list` command (view tasks) +- [ ] CLI: `complete` command (mark done) +- [ ] CLI: `delete` command (remove tasks) +- [ ] CLI: `edit` command (modify tasks) +- [ ] Comprehensive unit and integration tests (>80% coverage) + +### CLI Usage Examples + +```bash +# First run: initialize tasks folder +bevy-tasks init ~/Documents/Tasks + +# Or use a cloud-synced folder +bevy-tasks init ~/Dropbox/Tasks + +# Then use normally +bevy-tasks add "Buy groceries" --list "Personal" +bevy-tasks list +bevy-tasks list --list "Work" +bevy-tasks complete +bevy-tasks edit +bevy-tasks delete + +# Change folder location later +bevy-tasks config set-folder ~/new/location +``` + +### Deliverables + +- ✅ `bevy-tasks-core` library with stable API +- ✅ Functional CLI that can manage tasks +- ✅ Data persists as Obsidian-compatible .md files +- ✅ Well-tested backend (>80% coverage) +- ✅ Documentation for core library API + +### Development Setup + +```bash +# Clone and build +git clone +cd bevy-tasks +cargo build + +# Run tests +cargo test -p bevy-tasks-core + +# Run CLI +cargo run -p bevy-tasks-cli -- init ~/test-tasks +cargo run -p bevy-tasks-cli -- add "Test task" +cargo run -p bevy-tasks-cli -- list +``` + +--- + +## Phase 2: WebDAV Sync (Backend + CLI) + +**Goal**: Enable cross-device synchronization via CLI + +### Architecture + +#### WebDAV Integration + +Add WebDAV support to `bevy-tasks-core`: + +```rust +// Update AppConfig +AppConfig { + local_path: PathBuf, + webdav_url: Option, + webdav_credentials: Option, + last_sync: Option, + // ... +} + +// Add sync methods to TaskRepository +impl TaskRepository { + pub fn sync_push(&mut self) -> Result; + pub fn sync_pull(&mut self) -> Result; + pub fn sync_status(&self) -> Result; +} +``` + +#### Sync Strategy +- **Trigger**: On app start (if connected), background timer (every 5 min), on modification (debounced) +- **Conflict Resolution**: Last-write-wins with timestamp +- **Offline Support**: Queue operations when offline, sync when online + +#### Authentication + +**Primary**: Platform Keychain via `keyring` crate +- Store WebDAV username + password in system keychain +- Key format: `com.bevy-tasks.webdav.{server-domain}` +- Works on: Windows (Credential Manager), macOS (Keychain), Linux (Secret Service), iOS/Android (Keystore) + +**Fallback**: Encrypted local storage if keychain unavailable + +### Dependencies + +Add to `bevy-tasks-core/Cargo.toml`: +```toml +reqwest = { version = "0.12", features = ["json", "rustls-tls"] } +keyring = "3.0" +# TODO: Evaluate dav-client or implement custom WebDAV +``` + +### Features + +- [ ] WebDAV client implementation in core library +- [ ] Credential storage (platform keychain) +- [ ] Bi-directional sync (push/pull) +- [ ] Conflict resolution (last-write-wins) +- [ ] Offline queue for pending operations +- [ ] CLI: `sync --setup` command +- [ ] CLI: `sync --push` command +- [ ] CLI: `sync --pull` command +- [ ] CLI: `sync --status` command +- [ ] Progress indicators for sync operations + +### CLI Usage Examples + +```bash +# Setup WebDAV +bevy-tasks sync --setup +# Prompts for: URL, username, password (stored in keychain) + +# Manual sync +bevy-tasks sync --push +bevy-tasks sync --pull + +# Check sync status +bevy-tasks sync --status +``` + +### Deliverables + +- ✅ Working WebDAV sync in backend +- ✅ CLI can sync with remote WebDAV server +- ✅ Reliable conflict resolution +- ✅ Tested with Nextcloud, ownCloud + +--- + +## Phase 3: GUI MVP (Desktop) + +**Goal**: Build graphical interface on desktop platforms + +### Architecture + +#### Frontend Framework: egui + +**Decision**: Use egui (immediate mode GUI) for MVP + +**Why egui?** +- Fast development with rich built-in widgets +- Excellent text editing support out of the box +- Small binary size (~2-3MB stripped) +- Fast startup time (100-200ms target) +- Mature and stable +- Simple immediate-mode API +- Cross-platform (desktop AND mobile) +- Easy integration with `bevy-tasks-core` + +#### GUI Crate Structure + +``` +crates/bevy-tasks-gui/ +├── Cargo.toml +├── src/ +│ ├── main.rs # App entry point +│ ├── app.rs # egui app setup +│ ├── ui/ +│ │ ├── mod.rs +│ │ ├── screens/ +│ │ │ ├── task_list.rs +│ │ │ ├── task_detail.rs +│ │ │ └── settings.rs +│ │ └── components/ +│ │ ├── task_item.rs +│ │ ├── task_input.rs +│ │ └── list_selector.rs +│ └── state.rs # UI state management +├── assets/ +│ ├── fonts/ +│ └── icons/ +└── README.md +``` + +#### First Run Experience +- Show folder picker dialog on first launch +- User selects where to store tasks (e.g., `~/Documents/Tasks`) +- No default hidden directories +- Remember choice in app config + +### Dependencies + +**bevy-tasks-gui/Cargo.toml**: ```toml [package] name = "bevy-tasks-gui" @@ -680,204 +426,326 @@ edition = "2024" bevy-tasks-core = { path = "../bevy-tasks-core" } anyhow = { workspace = true } -# egui for Phase 3-5 +# egui for Phase 3-6 eframe = "0.31" # egui framework with native windowing egui = "0.31" # Core egui library - -# TODO Phase 6: Consider migration to Bevy for game-like polish -# bevy = { version = "0.16", default-features = false, features = ["bevy_ui", "bevy_render", "bevy_winit"] } - -# Platform-specific -[target.'cfg(target_os = "android")'.dependencies] -# Android-specific deps (Phase 5) - -[target.'cfg(target_os = "ios")'.dependencies] -# iOS-specific deps (Phase 5) ``` -## Getting Started +### Performance Strategy -### Prerequisites -- Rust 1.75+ (2024 edition) -- Platform-specific tools (for mobile builds later): - - **iOS**: macOS + Xcode - - **Android**: Android SDK + NDK +**Startup Sequence**: +1. Initialize eframe window (< 50ms) +2. Load config from disk (< 20ms) +3. Render empty UI (first frame < 100ms) +4. Load current task list in background +5. Update UI as tasks load +6. Start WebDAV sync in background (if configured) -### Development Setup -```bash -# Clone repository -git clone -cd bevy-tasks +**Target**: < 200ms cold start on desktop -# Build all workspace members -cargo build +**Optimizations**: +- Lazy data loading (load visible tasks first) +- Background operations for sync +- Efficient file I/O (stream large files) +- Minimal dependencies -# Run tests for core library -cargo test -p bevy-tasks-core +### Features -# Run CLI -cargo run -p bevy-tasks-cli -- --help -cargo run -p bevy-tasks-cli -- init ~/test-tasks +- [ ] egui framework integration +- [ ] Folder picker dialog on first launch +- [ ] Basic task list view +- [ ] Create new tasks +- [ ] Edit existing tasks +- [ ] Delete tasks +- [ ] Mark tasks complete/incomplete +- [ ] Settings screen (change folder, WebDAV config) +- [ ] Sync status indicators +- [ ] Desktop support (Windows, Linux, macOS) -# Run GUI (once implemented) -cargo run -p bevy-tasks-gui +### Deliverables -# Build for release -cargo build --release -p bevy-tasks-cli -cargo build --release -p bevy-tasks-gui +- ✅ Functional desktop GUI app +- ✅ Sub-200ms startup time +- ✅ Clean, minimal UI +- ✅ Feature parity with CLI -# Run all tests -cargo test --workspace -``` +### Build & Release -### Development Workflow (Phase 1) +**Distribution**: +- Linux: AppImage, .tar.gz +- macOS: DMG +- Windows: MSI, portable .exe -1. **Start with Core Library**: -```bash -cd crates/bevy-tasks-core -cargo test --watch # with cargo-watch -``` - -2. **Build CLI to test backend**: -```bash -cd crates/bevy-tasks-cli -cargo run -- init ~/Documents/TestTasks -cargo run -- add "Test task" -cargo run -- list -``` - -3. **Iterate on API**: -- Add features to core library -- Test via CLI -- Write integration tests -- Document public API - -4. **Add GUI later** (Phase 3): -```bash -cd crates/bevy-tasks-gui -cargo run -``` - -## Questions & Decisions - -### 1. Authentication for WebDAV Sync - -#### Option A: Platform Keychain/Keyring -**Implementation**: Use `keyring` crate for cross-platform credential storage - -**Pros**: -- Most secure option -- OS-managed encryption -- Follows platform security best practices -- Auto-locks with system -- Works on all platforms: - - Windows: Credential Manager - - macOS: Keychain - - Linux: Secret Service API (gnome-keyring/kwallet) - - iOS: Keychain - - Android: Keystore - -**Cons**: -- Requires user to unlock keychain -- May prompt for permissions -- Linux requires D-Bus and secret service - -**Security**: ⭐⭐⭐⭐⭐ - -#### Option B: Encrypted Local Storage -**Implementation**: Encrypt credentials in config file using a master password or device key - -**Pros**: -- Works offline always -- No external dependencies -- Full control over encryption - -**Cons**: -- Need to manage encryption keys -- Vulnerable if key is compromised -- Need to prompt user for password -- Harder to implement correctly - -**Security**: ⭐⭐⭐ (if done right) - -#### Option C: App-Generated Token + Keychain -**Implementation**: User authenticates once via OAuth/app-specific password, store token in keychain - -**Pros**: -- More secure than passwords -- Supports modern auth flows -- Can revoke tokens -- Works with Nextcloud, ownCloud app passwords - -**Cons**: -- Requires OAuth flow implementation -- More complex initial setup -- Depends on server support - -**Security**: ⭐⭐⭐⭐⭐ - -#### Option D: Store Username + Prompt for Password -**Implementation**: Store username in config, prompt for password on each sync - -**Pros**: -- Simple implementation -- No credential storage -- Maximum security - -**Cons**: -- Terrible UX -- Not practical for background sync -- Users will hate it - -**Security**: ⭐⭐⭐⭐⭐ (but unusable) - -#### Recommendation -**Primary**: Option A (Platform Keychain) using the `keyring` crate -- Store WebDAV username + password in system keychain -- Key: `com.bevy-tasks.webdav.{server-domain}` -- Graceful fallback if keychain is unavailable - -**Fallback**: Option B (Encrypted storage) for platforms where keychain fails -- Use ChaCha20-Poly1305 for encryption -- Derive key from device identifier + app secret - -**Future**: Option C (Token-based) for servers that support it -- Implement OAuth flow for Nextcloud/ownCloud -- Store tokens in keychain +**CI/CD**: GitHub Actions for automated builds --- -### 3. Backup Strategy +## Phase 4: Mobile Basic Support -**Decision**: User-managed backups via external tools +**Goal**: Get app running on iOS and Android ASAP, validate architecture -**Rationale**: -- Markdown format is already backup-friendly -- Users can use existing tools: - - Git for version control - - Dropbox/Google Drive/OneDrive for cloud backup - - Time Machine (macOS) / File History (Windows) - - rsync, rclone, etc. -- WebDAV itself serves as a backup when enabled -- Keeps app simple and focused +### Why Early Mobile? +- De-risk mobile builds early in development +- Test cross-platform architecture sooner +- Validate egui on mobile +- Get mobile-specific feedback early +- Can dogfood on mobile while building desktop features -**App Responsibilities**: -- Don't corrupt data -- Write atomically (temp file + rename) -- Graceful handling of sync conflicts -- Clear documentation on backup best practices +### Architecture -**Optional Future Feature**: -- Export all tasks to single file (.zip of markdown) -- Import from backup -- Git integration for automatic versioning +#### Mobile Build Setup + +**iOS**: +- Use Xcode for builds +- Target: `aarch64-apple-ios` +- Bundle identifier: `com.bevy-tasks` + +**Android**: +- Use Android SDK/NDK +- Build with `cargo-apk` or `cargo-ndk` +- Min SDK: 26 (Android 8.0) + +#### egui Mobile Adaptation + +**Touch Support**: +- egui has basic touch support +- Add larger touch targets (44pt minimum) +- Test on real devices + +**File System Access**: +- iOS: App sandbox documents directory + file picker +- Android: Scoped storage + SAF (Storage Access Framework) + +#### First Run on Mobile +- Show folder picker on first launch +- Suggest locations: Documents, iCloud Drive (iOS), Google Drive (Android) +- User selects folder, path stored in preferences + +### Platform-Specific Code + +```rust +#[cfg(target_os = "ios")] +mod ios { + // iOS-specific file picker, etc. +} + +#[cfg(target_os = "android")] +mod android { + // Android-specific file picker, etc. +} +``` + +### Features + +- [ ] iOS build pipeline setup (Xcode project) +- [ ] Android build pipeline setup (Gradle/NDK) +- [ ] Basic egui mobile adaptation +- [ ] Simple test UI (even just buttons for CRUD) +- [ ] File system access on iOS +- [ ] File system access on Android +- [ ] Folder picker for mobile +- [ ] Basic task CRUD on mobile +- [ ] Test on real devices + +### Deliverables + +- ✅ App launches on iOS +- ✅ App launches on Android +- ✅ Can create and view tasks on mobile +- ✅ Validates cross-platform architecture +- ✅ Foundation for future mobile polish + +### Distribution + +- iOS: .ipa for TestFlight (early access) +- Android: .apk (direct install / sideloading) + +**Note**: This phase prioritizes getting mobile working, even with a simple UI. Polish comes in Phase 6. + +--- + +## Phase 5: GUI Advanced Features (Desktop + Mobile) + +**Goal**: Feature parity with Google Tasks across all platforms + +### Features + +#### Desktop & Mobile +- [ ] Multiple task lists (folders) +- [ ] Switch between lists +- [ ] Subtasks support +- [ ] Due dates with date picker +- [ ] Rich markdown editor for task notes +- [ ] Move tasks between lists +- [ ] Change storage folder location in settings +- [ ] Search functionality +- [ ] Themes (light/dark mode) + +#### Desktop-Specific +- [ ] Drag & drop reordering +- [ ] Keyboard shortcuts +- [ ] Multiple windows (optional) + +#### Mobile-Specific +- [ ] Swipe gestures (swipe to complete, swipe to delete) +- [ ] Pull-to-refresh +- [ ] Touch-optimized UI elements +- [ ] Larger touch targets + +### Deliverables + +- ✅ Full-featured task manager on all platforms +- ✅ Polished UX on desktop +- ✅ Touch-optimized UX on mobile +- ✅ Consistent feature set across platforms + +--- + +## Phase 6: Mobile Polish & Platform-Specific Features + +**Goal**: Native mobile experience and deep platform integration + +### Features + +#### iOS-Specific +- [ ] Share extension (share to tasks) +- [ ] iOS widgets (home screen, lock screen) +- [ ] Siri shortcuts +- [ ] Haptic feedback +- [ ] iOS-native gestures +- [ ] App icon badge with task count +- [ ] Quick capture via 3D touch / long press +- [ ] iCloud Drive integration + +#### Android-Specific +- [ ] Share target (share to tasks) +- [ ] Android widgets (home screen) +- [ ] Quick settings tile +- [ ] Haptic feedback +- [ ] Material Design guidelines +- [ ] Google Drive integration + +#### Both Platforms +- [ ] Background sync on mobile +- [ ] Push notifications for due dates +- [ ] Notification actions (complete from notification) +- [ ] App shortcuts +- [ ] Platform-specific animations + +### Deliverables + +- ✅ Native-feeling mobile apps +- ✅ Deep platform integration +- ✅ Mobile-specific features + +### Distribution + +**App Store Distribution**: +- iOS: Apple App Store +- Android: Google Play Store +- Android: F-Droid (FOSS store) + +--- + +## Phase 7: Advanced Features & Imports + +**Goal**: Differentiate from Google Tasks, add unique features + +### Features + +#### Google Tasks Importer +- [ ] **Import from Google Tasks** (via API or export) +- [ ] Migrate tasks, lists, due dates, notes +- [ ] Preserve task hierarchy and order +- [ ] Easy onboarding for Google Tasks users + +#### Advanced Task Management +- [ ] Tags and custom fields +- [ ] Recurring tasks (daily, weekly, monthly, custom) +- [ ] Task templates (save common tasks) +- [ ] Bulk operations (select multiple, bulk edit) +- [ ] Full-text search across all tasks +- [ ] Filters and smart lists (e.g., "Due this week") +- [ ] Statistics and insights (completion rate, etc.) + +#### Integration & Automation +- [ ] Calendar integration (view tasks in calendar) +- [ ] Email to task (send email to create task) +- [ ] Voice input (speech-to-text for tasks) +- [ ] URL schemes / deep links +- [ ] Zapier integration (optional) + +#### Collaboration (Optional) +- [ ] Share lists with other users +- [ ] Collaborative editing +- [ ] Comments on tasks +- [ ] Activity log + +#### Customization & Polish +- [ ] Custom themes and color schemes +- [ ] Advanced animations (consider Bevy migration) +- [ ] Plugin system for extensions (optional) +- [ ] Custom fonts +- [ ] Export/import (backup/restore to .zip) + +### Optional: Bevy Migration + +If you want game-like polish after Phase 7: +- Migrate GUI from egui to Bevy +- Full control over animations and rendering +- Unique, polished look beyond standard apps +- Backend (`bevy-tasks-core`) stays identical +- Only rewrite `bevy-tasks-gui` crate + +### Deliverables + +- ✅ Polished, delightful UX +- ✅ Unique features not in Google Tasks +- ✅ Easy migration path from Google Tasks +- ✅ Distribution to all app stores + +### Final Distribution + +**All Platforms**: +- F-Droid (FOSS Android) +- Flathub (Linux Flatpak) +- Google Play Store (Android) +- Apple App Store (iOS and macOS) +- Microsoft Store (Windows) +- Direct downloads (all platforms) + +--- + +## Development Guidelines + +### Testing Strategy +- **Unit tests**: Data models and business logic +- **Integration tests**: Storage layer operations +- **E2E tests**: Critical user flows +- **Performance tests**: Startup time, large datasets +- **Platform tests**: Verify each platform build + +### Performance Budgets +- **Cold start**: < 200ms on desktop, < 500ms on mobile +- **First render**: < 100ms +- **Task creation**: < 50ms +- **Sync operation**: < 2s for typical dataset (< 1000 tasks) +- **Memory usage**: < 50MB on mobile, < 100MB on desktop + +### Version Scheme +Semantic versioning: `0.1.0 → 1.0.0` + +### CI/CD +GitHub Actions for all platforms + +--- ## Resources - [Bevy Documentation](https://bevyengine.org/) -- [Bevy Mobile Examples](https://github.com/bevyengine/bevy/tree/main/examples/mobile) +- [egui Documentation](https://docs.rs/egui/) - [WebDAV RFC 4918](https://datatracker.ietf.org/doc/html/rfc4918) -- [Google Tasks API](https://developers.google.com/tasks) (for feature reference) +- [Google Tasks API](https://developers.google.com/tasks) (for importer reference) ## License @@ -886,5 +754,5 @@ To be determined. --- **Last Updated**: 2025-10-27 -**Document Version**: 2.3 -**Status**: Ready to Implement - Mobile-First, User-Controlled Storage +**Document Version**: 3.0 +**Status**: Ready to Implement - Milestone-Driven Plan