From aefcae551645376aeeb9ddf516cf4705c0a9a029 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 16:02:57 +0000 Subject: [PATCH 01/19] Add comprehensive project plan for Bevy Tasks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This plan outlines the development of a local-first, cross-platform tasks application inspired by Google Tasks. Key features: - Cross-platform support (Windows, Linux, macOS, iOS, Android) - Fast startup time (< 500ms target) - Local file storage with optional WebDAV sync - Built with Bevy for future game-like UX polish - Phased development roadmap from MVP to advanced features The plan includes architecture design, technology stack, performance strategies, and detailed feature roadmap across 5 development phases. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 412 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 412 insertions(+) create mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..87ad1ee --- /dev/null +++ b/PLAN.md @@ -0,0 +1,412 @@ +# Bevy Tasks - Project Plan + +## 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. + +## Core Principles + +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 + +## Target Platforms + +- **Desktop**: Windows, Linux, macOS +- **Mobile**: iOS, Android + +## Technology Stack + +### Core Framework +- **Bevy 0.16+**: Game engine providing cross-platform rendering and ECS architecture +- **bevy_ui**: For immediate UI components +- **bevy_egui**: Optional for more complex UI widgets (if needed) + +### Data Storage Layer +- **serde**: Serialization/deserialization +- **serde_json** or **rmp-serde**: JSON or MessagePack for task data +- **directories**: Cross-platform path handling +- **tokio**: Async runtime for I/O operations +- **reqwest** + **dav-client**: WebDAV support + +### Mobile Platform Support +- **bevy_mobile_example**: Reference for iOS/Android builds +- **cargo-apk**: Android builds +- **xcode**: iOS builds + +### Performance Optimization +- **Lazy loading**: Load only visible data +- **Asset preprocessing**: Minimize runtime overhead +- **Minimal dependencies**: Keep binary size small +- **Release optimizations**: LTO, strip symbols + +## Architecture + +### Data Model + +``` +Task { + id: Uuid, + title: String, + notes: Option, + status: TaskStatus, // NotStarted, InProgress, Completed + due_date: Option, + created_at: DateTime, + updated_at: DateTime, + parent_id: Option, // For subtasks + position: i32, // For ordering +} + +TaskList { + id: Uuid, + title: String, + tasks: Vec, + created_at: DateTime, + updated_at: DateTime, + position: i32, +} + +AppConfig { + storage_type: StorageType, // Local or WebDAV + local_path: Option, + webdav_url: Option, + webdav_credentials: Option, + theme: Theme, + last_sync: Option, +} +``` + +### Module Structure + +``` +bevy-tasks/ +├── src/ +│ ├── main.rs # Entry point +│ ├── app.rs # Bevy app setup +│ ├── data/ +│ │ ├── mod.rs +│ │ ├── models.rs # Task, TaskList, AppConfig +│ │ ├── repository.rs # Data access abstraction +│ │ └── storage/ +│ │ ├── mod.rs +│ │ ├── local.rs # Local file storage +│ │ └── webdav.rs # WebDAV client +│ ├── ui/ +│ │ ├── mod.rs +│ │ ├── screens/ +│ │ │ ├── task_list.rs +│ │ │ ├── task_detail.rs +│ │ │ └── settings.rs +│ │ └── components/ +│ │ ├── task_item.rs +│ │ ├── task_input.rs +│ │ └── list_selector.rs +│ ├── systems/ +│ │ ├── mod.rs +│ │ ├── input.rs # Input handling +│ │ ├── sync.rs # Background sync +│ │ └── navigation.rs # Screen navigation +│ └── resources/ +│ ├── mod.rs +│ └── app_state.rs # Global state management +├── assets/ +│ ├── fonts/ +│ └── icons/ +├── Cargo.toml +└── PLAN.md +``` + +### Storage Strategy + +#### Local Storage +- **Location**: Platform-specific app data directory + - Windows: `%APPDATA%/bevy-tasks/` + - Linux: `~/.local/share/bevy-tasks/` + - macOS: `~/Library/Application Support/bevy-tasks/` + - iOS: App sandbox documents directory + - Android: Internal storage app directory +- **Format**: JSON files (human-readable, debuggable) +- **Structure**: + ``` + data/ + ├── config.json + ├── lists/ + │ ├── {list-id-1}.json + │ └── {list-id-2}.json + └── metadata.json + ``` + +#### 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 UI rendering**: Render visible items first +3. **Background loading**: Load non-critical data after first frame +4. **Asset optimization**: Embed minimal assets, load rest async +5. **Incremental parsing**: Stream large data files + +#### Startup Sequence +1. Initialize Bevy minimal plugins (< 50ms) +2. Load config from disk (< 20ms) +3. Render splash/empty state (first frame < 100ms) +4. Load task lists in background +5. Render tasks as they load +6. Start WebDAV sync (if configured) + +#### Memory Optimization +- Use `Vec` instead of `HashMap` for small collections +- Limit rendered tasks to visible viewport +- Unload non-visible screens from memory + +## Feature Roadmap + +### Phase 1: MVP (Weeks 1-4) +**Goal**: Basic local-first tasks app on desktop platforms + +**Features**: +- [ ] Single task list +- [ ] Create, read, update, delete tasks +- [ ] Mark tasks as complete/incomplete +- [ ] Local file storage (JSON) +- [ ] Basic UI (list view) +- [ ] Desktop support (Windows, Linux, macOS) + +**Deliverables**: +- Functional desktop app +- Data persists across sessions +- Sub-second startup time + +### Phase 2: Multiple Lists & Organization (Weeks 5-6) +**Goal**: Feature parity with basic Google Tasks functionality + +**Features**: +- [ ] Multiple task lists +- [ ] Switch between lists +- [ ] Subtasks support +- [ ] Due dates +- [ ] Task notes/descriptions +- [ ] Reorder tasks (drag & drop) +- [ ] Move tasks between lists + +**Deliverables**: +- Full task management functionality +- Improved UI/UX + +### Phase 3: WebDAV Sync (Weeks 7-9) +**Goal**: Enable cross-device synchronization + +**Features**: +- [ ] WebDAV client implementation +- [ ] Settings screen for storage configuration +- [ ] Sync status indicators +- [ ] Conflict resolution +- [ ] Offline mode with queue +- [ ] Manual sync trigger + +**Deliverables**: +- Working WebDAV sync +- Reliable conflict resolution +- Seamless offline/online transitions + +### Phase 4: Mobile Support (Weeks 10-14) +**Goal**: Deploy to iOS and Android + +**Features**: +- [ ] Touch-optimized UI +- [ ] iOS build pipeline +- [ ] Android build pipeline +- [ ] Mobile-specific UX (swipe gestures, etc.) +- [ ] Background sync on mobile +- [ ] Push notifications (optional) + +**Deliverables**: +- Working iOS app +- Working Android app +- Consistent UX across mobile and desktop + +### Phase 5: Polish & Advanced Features (Weeks 15+) +**Goal**: Differentiate from Google Tasks, leverage Bevy's capabilities + +**Features**: +- [ ] Themes and customization +- [ ] Advanced animations +- [ ] Keyboard shortcuts +- [ ] Search and filters +- [ ] Task templates +- [ ] Recurring tasks +- [ ] Statistics and insights +- [ ] Game-like achievement system (optional) +- [ ] Custom UI skins + +**Deliverables**: +- Polished, delightful UX +- Unique features not in Google Tasks + +## 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 +- **Desktop**: Direct downloads (AppImage, DMG, MSI) +- **Mobile**: App Store and Google Play +- **Version scheme**: Semantic versioning (0.1.0 → 1.0.0) + +## Technical Challenges & Solutions + +### Challenge 1: Fast Startup with Bevy +**Problem**: Bevy's plugin system can add overhead + +**Solutions**: +- Use `MinimalPlugins` instead of `DefaultPlugins` +- Add only required plugins (rendering, input) +- Lazy-load audio, asset server if not needed immediately +- Profile startup and optimize hot paths + +### Challenge 2: Mobile Platform Support +**Problem**: iOS and Android have different requirements + +**Solutions**: +- Use conditional compilation for platform-specific code +- Test early and often on real devices +- Follow platform guidelines (iOS HIG, Material Design) +- Use platform-specific file pickers and sharing + +### Challenge 3: WebDAV Reliability +**Problem**: Network can be unreliable, auth can be complex + +**Solutions**: +- Implement robust retry logic with exponential backoff +- Cache credentials securely (use platform keychains) +- 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 data format from day one +- Write migration scripts for each version bump +- Test migrations with real user data +- Backup before migration + +## Success Metrics + +### Performance +- ✓ Startup time < 500ms on mid-range devices +- ✓ 60 FPS UI on all platforms +- ✓ Handle 10,000+ tasks without performance degradation + +### User Experience +- ✓ Task creation in < 3 taps/clicks +- ✓ Zero data loss +- ✓ Sync conflicts rare and auto-resolved + +### Platform Support +- ✓ All 5 platforms working +- ✓ Consistent feature set across platforms +- ✓ Native feel on each platform + +## Dependencies + +### Core Dependencies +```toml +[dependencies] +bevy = "0.16" +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +uuid = { version = "1.0", features = ["serde", "v4"] } +chrono = { version = "0.4", features = ["serde"] } +directories = "5.0" +tokio = { version = "1.0", features = ["full"] } +anyhow = "1.0" + +# WebDAV support +reqwest = { version = "0.11", features = ["json"] } +# Note: Evaluate dav-client alternatives + +# Platform-specific +[target.'cfg(target_os = "android")'.dependencies] +# Android-specific deps + +[target.'cfg(target_os = "ios")'.dependencies] +# iOS-specific deps +``` + +## Getting Started + +### Prerequisites +- Rust 1.75+ (Bevy 0.16 requirement) +- Platform-specific tools: + - **iOS**: macOS + Xcode + - **Android**: Android SDK + NDK + +### Development Setup +```bash +# Clone repository +git clone +cd bevy-tasks + +# Run desktop version +cargo run + +# Build for release +cargo build --release + +# Run tests +cargo test + +# Build for Android +cargo apk build --release + +# Build for iOS (on macOS) +cargo build --target aarch64-apple-ios --release +``` + +## Questions & Decisions Needed + +1. **UI Framework**: Pure bevy_ui or bevy_egui for complex widgets? +2. **Data Format**: JSON (human-readable) or MessagePack (efficient)? +3. **Authentication**: How to securely store WebDAV credentials? +4. **Distribution**: Self-hosted only or aim for app stores? +5. **Backup Strategy**: Automatic local backups? Export functionality? + +## Resources + +- [Bevy Documentation](https://bevyengine.org/) +- [Bevy Mobile Examples](https://github.com/bevyengine/bevy/tree/main/examples/mobile) +- [WebDAV RFC 4918](https://datatracker.ietf.org/doc/html/rfc4918) +- [Google Tasks API](https://developers.google.com/tasks) (for feature reference) + +## License + +To be determined. + +--- + +**Last Updated**: 2025-10-26 +**Document Version**: 1.0 +**Status**: Planning Phase From 219516e863b1c8e61159298b1c4e566179c4883c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 26 Oct 2025 23:46:37 +0000 Subject: [PATCH 02/19] Update project plan with detailed decisions and markdown format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Key changes: - Changed data format to Markdown files with YAML frontmatter (Obsidian-compatible) - Removed timeline estimates from all phases - Added comprehensive UI framework analysis (bevy_ui vs bevy_egui) - Added detailed authentication options for WebDAV (keychain recommended) - Expanded distribution strategy to include all app stores (F-Droid, Flathub, etc.) - Clarified backup strategy as user-managed via external tools - Removed success metrics section - Added markdown benefits: human-readable, git-friendly, tool-compatible Decisions made: - Recommend pure bevy_ui for performance and future game-like polish - Use platform keychain (keyring crate) for WebDAV credentials - Users handle backups via git, cloud storage, or other external tools 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 359 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 291 insertions(+), 68 deletions(-) diff --git a/PLAN.md b/PLAN.md index 87ad1ee..3295361 100644 --- a/PLAN.md +++ b/PLAN.md @@ -26,7 +26,8 @@ A local-first, cross-platform tasks application inspired by Google Tasks, built ### Data Storage Layer - **serde**: Serialization/deserialization -- **serde_json** or **rmp-serde**: JSON or MessagePack for task data +- **pulldown-cmark** or **markdown**: Markdown parsing +- **gray_matter** or **yaml-rust**: YAML frontmatter parsing (Obsidian-style metadata) - **directories**: Cross-platform path handling - **tokio**: Async runtime for I/O operations - **reqwest** + **dav-client**: WebDAV support @@ -46,22 +47,46 @@ A local-first, cross-platform tasks application inspired by Google Tasks, built ### Data Model +Tasks are stored as individual `.md` (Markdown) files, with metadata in YAML frontmatter (Obsidian-compatible format). + ``` +Task File Format (my-task-name.md): +--- +id: 550e8400-e29b-41d4-a716-446655440000 +status: in-progress +due: 2025-11-15T14:00:00Z +created: 2025-10-26T10:00:00Z +updated: 2025-10-26T12:30:00Z +parent: 550e8400-e29b-41d4-a716-446655440001 +position: 1 +tags: [work, urgent] +--- + +Task description and notes go here in **markdown** format. + +- Can include lists +- Rich formatting +- Links, etc. +``` + +**In-Memory Model**: +```rust Task { id: Uuid, - title: String, - notes: Option, - status: TaskStatus, // NotStarted, InProgress, Completed - due_date: Option, - created_at: DateTime, - updated_at: DateTime, - parent_id: Option, // For subtasks - position: i32, // For ordering + title: String, // Derived from filename + 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 } TaskList { id: Uuid, - title: String, + title: String, // Derived from folder name tasks: Vec, created_at: DateTime, updated_at: DateTime, @@ -121,23 +146,38 @@ bevy-tasks/ ### Storage Strategy #### Local Storage -- **Location**: Platform-specific app data directory - - Windows: `%APPDATA%/bevy-tasks/` - - Linux: `~/.local/share/bevy-tasks/` - - macOS: `~/Library/Application Support/bevy-tasks/` +- **Location**: User-selectable folder OR platform-specific app data directory + - Windows: `%APPDATA%/bevy-tasks/` (default) + - Linux: `~/.local/share/bevy-tasks/` (default) + - macOS: `~/Library/Application Support/bevy-tasks/` (default) - iOS: App sandbox documents directory - Android: Internal storage app directory -- **Format**: JSON files (human-readable, debuggable) + - User can select any folder with read/write permissions +- **Format**: Markdown files with YAML frontmatter (Obsidian-compatible) - **Structure**: ``` data/ - ├── config.json - ├── lists/ - │ ├── {list-id-1}.json - │ └── {list-id-2}.json - └── metadata.json + ├── .bevy-tasks/ + │ ├── config.json # App configuration + │ └── 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 ``` +**Benefits of Markdown Format**: +- Human-readable and editable in any text editor +- Compatible with Obsidian, Logseq, and other markdown tools +- Easy to version control (git-friendly) +- Future-proof format +- Enables external editing and scripting +- Natural organization with folders + #### WebDAV Sync - **Conflict Resolution**: Last-write-wins with timestamp - **Sync Strategy**: @@ -170,87 +210,96 @@ bevy-tasks/ ## Feature Roadmap -### Phase 1: MVP (Weeks 1-4) +### Phase 1: MVP **Goal**: Basic local-first tasks app on desktop platforms **Features**: - [ ] Single task list - [ ] Create, read, update, delete tasks - [ ] Mark tasks as complete/incomplete -- [ ] Local file storage (JSON) +- [ ] Local file storage (Markdown files) +- [ ] Markdown parsing with YAML frontmatter - [ ] Basic UI (list view) - [ ] Desktop support (Windows, Linux, macOS) **Deliverables**: - Functional desktop app -- Data persists across sessions +- Data persists across sessions as .md files - Sub-second startup time -### Phase 2: Multiple Lists & Organization (Weeks 5-6) +### Phase 2: Multiple Lists & Organization **Goal**: Feature parity with basic Google Tasks functionality **Features**: -- [ ] Multiple task lists +- [ ] Multiple task lists (folders) - [ ] Switch between lists -- [ ] Subtasks support -- [ ] Due dates -- [ ] Task notes/descriptions -- [ ] Reorder tasks (drag & drop) -- [ ] Move tasks between lists +- [ ] Subtasks support (nested folders or parent_id) +- [ ] Due dates (frontmatter metadata) +- [ ] Task notes/descriptions (markdown content) +- [ ] Reorder tasks (drag & drop, updates position) +- [ ] Move tasks between lists (move .md files) +- [ ] Folder picker for custom storage location **Deliverables**: - Full task management functionality - Improved UI/UX +- Obsidian-compatible file format -### Phase 3: WebDAV Sync (Weeks 7-9) +### Phase 3: WebDAV Sync **Goal**: Enable cross-device synchronization **Features**: - [ ] WebDAV client implementation - [ ] Settings screen for storage configuration +- [ ] Credential storage (see Authentication section) - [ ] Sync status indicators -- [ ] Conflict resolution +- [ ] Conflict resolution (last-write-wins with manual review option) - [ ] Offline mode with queue - [ ] Manual sync trigger +- [ ] Bi-directional sync of .md files **Deliverables**: - Working WebDAV sync - Reliable conflict resolution - Seamless offline/online transitions -### Phase 4: Mobile Support (Weeks 10-14) +### Phase 4: Mobile Support **Goal**: Deploy to iOS and Android **Features**: - [ ] Touch-optimized UI - [ ] iOS build pipeline - [ ] Android build pipeline -- [ ] Mobile-specific UX (swipe gestures, etc.) +- [ ] Mobile-specific UX (swipe gestures, pull-to-refresh) - [ ] Background sync on mobile -- [ ] Push notifications (optional) +- [ ] Mobile file system integration +- [ ] Share extension (share to tasks) **Deliverables**: - Working iOS app - Working Android app - Consistent UX across mobile and desktop -### Phase 5: Polish & Advanced Features (Weeks 15+) +### Phase 5: Polish & Advanced Features **Goal**: Differentiate from Google Tasks, leverage Bevy's capabilities **Features**: - [ ] Themes and customization -- [ ] Advanced animations +- [ ] Advanced animations and transitions - [ ] Keyboard shortcuts -- [ ] Search and filters +- [ ] Full-text search across tasks +- [ ] Filters and smart lists - [ ] Task templates - [ ] Recurring tasks - [ ] Statistics and insights - [ ] Game-like achievement system (optional) - [ ] Custom UI skins +- [ ] Plugin system for extensions **Deliverables**: - Polished, delightful UX - Unique features not in Google Tasks +- Distribution to all app stores ## Development Guidelines @@ -270,9 +319,22 @@ bevy-tasks/ ### Build & Release - **CI/CD**: GitHub Actions for all platforms -- **Desktop**: Direct downloads (AppImage, DMG, MSI) -- **Mobile**: App Store and Google Play +- **Initial Distribution**: + - **Desktop**: Direct downloads and sideloading + - Linux: AppImage, .tar.gz + - macOS: DMG + - Windows: MSI, portable .exe + - **Mobile**: Sideloading only + - iOS: .ipa for TestFlight/direct install + - Android: .apk +- **Future Distribution Channels** (Phase 5+): + - **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 @@ -299,7 +361,7 @@ bevy-tasks/ **Solutions**: - Implement robust retry logic with exponential backoff -- Cache credentials securely (use platform keychains) +- Cache credentials securely (see Authentication Options below) - Queue operations when offline - Provide clear sync status to user - Support multiple WebDAV servers (Nextcloud, ownCloud, etc.) @@ -308,27 +370,11 @@ bevy-tasks/ **Problem**: Schema changes need to preserve user data **Solutions**: -- Version data format from day one +- Version frontmatter schema from day one - Write migration scripts for each version bump -- Test migrations with real user data -- Backup before migration - -## Success Metrics - -### Performance -- ✓ Startup time < 500ms on mid-range devices -- ✓ 60 FPS UI on all platforms -- ✓ Handle 10,000+ tasks without performance degradation - -### User Experience -- ✓ Task creation in < 3 taps/clicks -- ✓ Zero data loss -- ✓ Sync conflicts rare and auto-resolved - -### Platform Support -- ✓ All 5 platforms working -- ✓ Consistent feature set across platforms -- ✓ Native feel on each platform +- Markdown format is naturally forward/backward compatible +- Users handle their own backups (external to app) +- Migration can be done in-place by updating frontmatter ## Dependencies @@ -338,6 +384,8 @@ bevy-tasks/ bevy = "0.16" serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" +serde_yaml = "0.9" # For frontmatter parsing +pulldown-cmark = "0.9" # Markdown parsing uuid = { version = "1.0", features = ["serde", "v4"] } chrono = { version = "0.4", features = ["serde"] } directories = "5.0" @@ -348,6 +396,9 @@ anyhow = "1.0" reqwest = { version = "0.11", features = ["json"] } # Note: Evaluate dav-client alternatives +# Credential storage (see Authentication Options) +keyring = "2.0" # Cross-platform keychain access + # Platform-specific [target.'cfg(target_os = "android")'.dependencies] # Android-specific deps @@ -386,13 +437,185 @@ cargo apk build --release cargo build --target aarch64-apple-ios --release ``` -## Questions & Decisions Needed +## Questions & Decisions -1. **UI Framework**: Pure bevy_ui or bevy_egui for complex widgets? -2. **Data Format**: JSON (human-readable) or MessagePack (efficient)? -3. **Authentication**: How to securely store WebDAV credentials? -4. **Distribution**: Self-hosted only or aim for app stores? -5. **Backup Strategy**: Automatic local backups? Export functionality? +### 1. UI Framework: bevy_ui vs bevy_egui + +#### Option A: Pure bevy_ui +**Pros**: +- Native to Bevy, no additional dependencies +- Full control over rendering and styling +- Better performance (no intermediate UI layer) +- Fits Bevy's ECS paradigm perfectly +- More flexibility for game-like UX polish later +- Smaller binary size +- Consistent cross-platform look + +**Cons**: +- More verbose, lower-level API +- Need to build complex widgets from scratch +- Text input handling requires more work +- Fewer built-in widgets +- Steeper learning curve for complex layouts +- More code to maintain + +**Best for**: If you want maximum performance, full control, and are willing to invest time building custom widgets. + +#### Option B: bevy_egui +**Pros**: +- Rich set of built-in widgets (text input, combo boxes, etc.) +- Immediate mode GUI is simple to reason about +- Rapid prototyping and iteration +- Good text editing support out of the box +- Mature ecosystem +- Less code for standard UI patterns +- Better accessibility features + +**Cons**: +- Additional dependency (~500KB+) +- Slight performance overhead +- Less control over rendering +- Immediate mode pattern conflicts with ECS +- Harder to achieve game-like polish +- Less Bevy-native feel +- More challenging to customize appearance + +**Best for**: If you want to ship quickly with standard UI widgets and don't need deep customization. + +#### Option C: Hybrid Approach +Use **bevy_ui** for primary interface (task lists, main views) and **bevy_egui** for complex forms and settings screens. + +**Pros**: +- Best of both worlds +- Use right tool for each job +- Fast development where needed, optimized where it matters + +**Cons**: +- Two UI systems to learn and maintain +- Increased binary size +- Inconsistent look without careful styling + +#### Recommendation +Start with **pure bevy_ui** for MVP. The task list UI is relatively simple (lists, buttons, text), and this gives you: +- Maximum performance for fast startup +- Foundation for future game-like polish +- Full control over mobile UX + +Reserve bevy_egui as a fallback if text editing becomes too complex to implement. + +--- + +### 2. Authentication Options for WebDAV + +#### 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 + +--- + +### 3. Backup Strategy + +**Decision**: User-managed backups via external tools + +**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 + +**App Responsibilities**: +- Don't corrupt data +- Write atomically (temp file + rename) +- Graceful handling of sync conflicts +- Clear documentation on backup best practices + +**Optional Future Feature**: +- Export all tasks to single file (.zip of markdown) +- Import from backup +- Git integration for automatic versioning ## Resources @@ -408,5 +631,5 @@ To be determined. --- **Last Updated**: 2025-10-26 -**Document Version**: 1.0 +**Document Version**: 1.1 **Status**: Planning Phase From 501970605536b38831bbc9704198b80b41c7f559 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 00:14:19 +0000 Subject: [PATCH 03/19] Refactor plan: Backend/Frontend separation with CLI-first approach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major architectural changes: - Reorganized as Cargo workspace with 3 crates: - bevy-tasks-core: Pure Rust library (no UI dependencies) - bevy-tasks-cli: Command-line interface - bevy-tasks-gui: Graphical frontend (framework TBD) CLI-First Development Strategy: - Phase 1: Build core library + CLI MVP (validate backend) - Phase 2: Add WebDAV sync to backend + CLI - Phase 3: Build GUI MVP using chosen framework - Phases 4-6: Mobile, polish, and advanced features Comprehensive Frontend Framework Comparison: Added detailed analysis of 8 frontend options: 1. Bevy (game engine) - best for polish, harder for standard UI 2. egui (immediate mode) - RECOMMENDED for MVP (fast, simple) 3. Iced (Elm-inspired) - good for desktop, mobile experimental 4. Dioxus (React-like) - web-friendly, mobile uses webview 5. Tauri (web + Rust) - uses system webview, slower startup 6. Slint (declarative) - clean but smaller community 7. Flutter (Dart) - best mobile but not Rust 8. Native UIs - best native feel but 5x development effort Recommendation: Start with egui for Phase 3 MVP, optionally migrate to Bevy in Phase 6 for game-like polish. Backend separation makes this possible without rewriting business logic. Benefits of this approach: - Test backend thoroughly before GUI complexity - CLI useful for power users and automation - Clean API boundaries - Easy to swap frontend frameworks - Parallel development possible after Phase 2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 806 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 624 insertions(+), 182 deletions(-) diff --git a/PLAN.md b/PLAN.md index 3295361..d1904a1 100644 --- a/PLAN.md +++ b/PLAN.md @@ -19,29 +19,44 @@ A local-first, cross-platform tasks application inspired by Google Tasks, built ## Technology Stack -### Core Framework -- **Bevy 0.16+**: Game engine providing cross-platform rendering and ECS architecture -- **bevy_ui**: For immediate UI components -- **bevy_egui**: Optional for more complex UI widgets (if needed) +### Project Structure: Workspace with Backend/Frontend Separation -### Data Storage Layer +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 -- **gray_matter** or **yaml-rust**: YAML frontmatter parsing (Obsidian-style metadata) +- **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 -### Mobile Platform Support -- **bevy_mobile_example**: Reference for iOS/Android builds -- **cargo-apk**: Android builds -- **xcode**: iOS builds +### 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 -- **Asset preprocessing**: Minimize runtime overhead - **Minimal dependencies**: Keep binary size small - **Release optimizations**: LTO, strip symbols +- **Backend separation**: Core logic has zero UI overhead ## Architecture @@ -103,44 +118,112 @@ AppConfig { } ``` -### Module Structure +### Workspace Structure ``` bevy-tasks/ -├── src/ -│ ├── main.rs # Entry point -│ ├── app.rs # Bevy app setup -│ ├── data/ -│ │ ├── mod.rs -│ │ ├── models.rs # Task, TaskList, AppConfig -│ │ ├── repository.rs # Data access abstraction -│ │ └── storage/ -│ │ ├── mod.rs -│ │ ├── local.rs # Local file storage -│ │ └── webdav.rs # WebDAV client -│ ├── ui/ -│ │ ├── mod.rs -│ │ ├── screens/ -│ │ │ ├── task_list.rs -│ │ │ ├── task_detail.rs -│ │ │ └── settings.rs -│ │ └── components/ -│ │ ├── task_item.rs -│ │ ├── task_input.rs -│ │ └── list_selector.rs -│ ├── systems/ -│ │ ├── mod.rs -│ │ ├── input.rs # Input handling -│ │ ├── sync.rs # Background sync -│ │ └── navigation.rs # Screen navigation -│ └── resources/ -│ ├── mod.rs -│ └── app_state.rs # Global state management -├── assets/ -│ ├── fonts/ -│ └── icons/ -├── Cargo.toml -└── PLAN.md +├── 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 +``` + +### Core Library API Design + +The `bevy-tasks-core` library will expose a clean, high-level API: + +```rust +// Main repository interface +pub struct TaskRepository { + storage: Box, +} + +impl TaskRepository { + pub fn new(config: Config) -> Result; + pub fn init(path: PathBuf) -> Result; + + // Task operations + pub fn create_task(&mut self, list_id: Uuid, task: Task) -> Result; + pub fn get_task(&self, id: Uuid) -> Result; + pub fn update_task(&mut self, task: Task) -> Result<()>; + pub fn delete_task(&mut self, id: Uuid) -> Result<()>; + pub fn list_tasks(&self, list_id: Uuid) -> Result>; + + // List operations + 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<()>; + // ... more methods +} ``` ### Storage Strategy @@ -210,60 +293,99 @@ bevy-tasks/ ## Feature Roadmap -### Phase 1: MVP -**Goal**: Basic local-first tasks app on desktop platforms +### Phase 1: Core Library & CLI MVP +**Goal**: Build and validate the backend with a functional CLI **Features**: -- [ ] Single task list -- [ ] Create, read, update, delete tasks -- [ ] Mark tasks as complete/incomplete -- [ ] Local file storage (Markdown files) -- [ ] Markdown parsing with YAML frontmatter -- [ ] Basic UI (list view) -- [ ] Desktop support (Windows, Linux, macOS) +- [ ] 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**: -- Functional desktop app -- Data persists across sessions as .md files -- Sub-second startup time +- `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) -### Phase 2: Multiple Lists & Organization -**Goal**: Feature parity with basic Google Tasks functionality +**CLI Example**: +```bash +bevy-tasks init ~/my-tasks +bevy-tasks add "Buy groceries" --list "Personal" +bevy-tasks list +bevy-tasks complete +``` + +### 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 + +**Frontend Decision**: Choose frontend framework (see Frontend Comparison section) + +**Features**: +- [ ] GUI framework integration +- [ ] Basic task list view +- [ ] Create/edit/delete tasks +- [ ] Mark tasks complete +- [ ] Settings screen (storage 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: GUI Advanced Features (Desktop) +**Goal**: Feature parity with Google Tasks **Features**: - [ ] Multiple task lists (folders) - [ ] Switch between lists -- [ ] Subtasks support (nested folders or parent_id) -- [ ] Due dates (frontmatter metadata) -- [ ] Task notes/descriptions (markdown content) -- [ ] Reorder tasks (drag & drop, updates position) -- [ ] Move tasks between lists (move .md files) -- [ ] Folder picker for custom storage location +- [ ] Subtasks support +- [ ] Due dates with date picker +- [ ] Rich markdown editor for task notes +- [ ] Drag & drop reordering +- [ ] Move tasks between lists +- [ ] Folder picker for custom storage +- [ ] Keyboard shortcuts +- [ ] Search functionality **Deliverables**: -- Full task management functionality -- Improved UI/UX -- Obsidian-compatible file format +- Full-featured desktop task manager +- Polished UX +- Keyboard-driven workflow -### Phase 3: WebDAV Sync -**Goal**: Enable cross-device synchronization - -**Features**: -- [ ] WebDAV client implementation -- [ ] Settings screen for storage configuration -- [ ] Credential storage (see Authentication section) -- [ ] Sync status indicators -- [ ] Conflict resolution (last-write-wins with manual review option) -- [ ] Offline mode with queue -- [ ] Manual sync trigger -- [ ] Bi-directional sync of .md files - -**Deliverables**: -- Working WebDAV sync -- Reliable conflict resolution -- Seamless offline/online transitions - -### Phase 4: Mobile Support +### Phase 5: Mobile Support **Goal**: Deploy to iOS and Android **Features**: @@ -274,27 +396,27 @@ bevy-tasks/ - [ ] Background sync on mobile - [ ] Mobile file system integration - [ ] Share extension (share to tasks) +- [ ] Native mobile feel **Deliverables**: - Working iOS app - Working Android app - Consistent UX across mobile and desktop -### Phase 5: Polish & Advanced Features -**Goal**: Differentiate from Google Tasks, leverage Bevy's capabilities +### Phase 6: Polish & Advanced Features +**Goal**: Differentiate from Google Tasks, add unique features **Features**: - [ ] Themes and customization -- [ ] Advanced animations and transitions -- [ ] Keyboard shortcuts +- [ ] Advanced animations and transitions (if using Bevy) - [ ] Full-text search across tasks - [ ] Filters and smart lists - [ ] Task templates - [ ] Recurring tasks - [ ] Statistics and insights -- [ ] Game-like achievement system (optional) -- [ ] Custom UI skins -- [ ] Plugin system for extensions +- [ ] Export/import (backup) +- [ ] Plugin system for extensions (optional) +- [ ] Game-like achievements (optional, if using Bevy) **Deliverables**: - Polished, delightful UX @@ -376,28 +498,373 @@ bevy-tasks/ - Users handle their own backups (external to app) - Migration can be done in-place by updating frontmatter +## Frontend Framework Comparison + +Now that we have backend/frontend separation, we can evaluate multiple GUI framework options. The backend (`bevy-tasks-core`) is framework-agnostic. + +### Option 1: Bevy (Game Engine) +**Language**: Rust +**Architecture**: ECS (Entity Component System) + +**Pros**: +- ✅ True cross-platform (Windows, Linux, macOS, iOS, Android, WASM) +- ✅ Excellent performance (60+ FPS easily) +- ✅ Future game-like polish and animations +- ✅ Active community and development +- ✅ Full control over rendering +- ✅ Single codebase for all platforms +- ✅ Fast startup possible with `MinimalPlugins` + +**Cons**: +- ❌ UI system is still maturing (bevy_ui improving but limited) +- ❌ More code required for standard widgets +- ❌ Steeper learning curve (ECS paradigm) +- ❌ Larger binary size (~5-10MB stripped) +- ❌ Text input handling requires extra work +- ❌ Not designed for traditional UIs + +**Best for**: If you want game-like polish, animations, and are willing to build custom UI components. + +**Startup time estimate**: 200-500ms +**Binary size**: 5-10MB (stripped) + +--- + +### Option 2: egui (Immediate Mode GUI) +**Language**: Rust +**Integration**: Standalone or with eframe + +**Pros**: +- ✅ True cross-platform (desktop, WASM, can run on mobile) +- ✅ Very simple API (immediate mode) +- ✅ Rich built-in widgets +- ✅ Excellent text editing support +- ✅ Small binary size (~2-3MB) +- ✅ Fast development iteration +- ✅ Mature and stable +- ✅ Good performance +- ✅ Works with multiple backends (glow, wgpu) + +**Cons**: +- ❌ Mobile support exists but less mature +- ❌ Immediate mode can be unusual coming from retained mode +- ❌ Less flexibility for custom animations +- ❌ Harder to achieve "game-like" polish +- ❌ Less native feel on each platform + +**Best for**: Quick development, standard UI needs, if you don't need game-like features. + +**Startup time estimate**: 100-200ms +**Binary size**: 2-3MB (stripped) + +--- + +### Option 3: Iced (Elm-inspired) +**Language**: Rust +**Architecture**: The Elm Architecture (TEA) + +**Pros**: +- ✅ Cross-platform (Windows, Linux, macOS, WASM) +- ✅ Declarative, reactive UI (similar to SwiftUI/Flutter) +- ✅ Clean architecture with clear state management +- ✅ Type-safe +- ✅ Good widget library +- ✅ Native-feeling widgets +- ✅ Async support built-in +- ✅ Medium binary size (~3-5MB) + +**Cons**: +- ❌ Mobile support experimental (iOS/Android not production-ready) +- ❌ Smaller community than egui or Bevy +- ❌ Still evolving (breaking changes possible) +- ❌ Limited animation capabilities +- ❌ Less documentation than mature frameworks + +**Best for**: If you like reactive/declarative UIs and primarily target desktop + WASM. + +**Startup time estimate**: 150-300ms +**Binary size**: 3-5MB (stripped) + +--- + +### Option 4: Dioxus (React-like) +**Language**: Rust +**Architecture**: Virtual DOM with React-like hooks + +**Pros**: +- ✅ Cross-platform (desktop, web, mobile via TUI or webview) +- ✅ React-like API (familiar to web devs) +- ✅ Hot reload support +- ✅ Component-based architecture +- ✅ Fast development +- ✅ Can target web with same code +- ✅ Active development + +**Cons**: +- ❌ Mobile support uses webview (not truly native) +- ❌ Still young and evolving +- ❌ Less mature than other options +- ❌ Performance not as good as native solutions +- ❌ Webview adds overhead on mobile + +**Best for**: Web developers wanting familiar patterns, prioritizing web deployment. + +**Startup time estimate**: 200-400ms (desktop), slower on mobile (webview) +**Binary size**: 4-8MB (includes webview on mobile) + +--- + +### Option 5: Tauri (Web Tech + Rust Backend) +**Language**: HTML/CSS/JavaScript (or any web framework) + Rust +**Architecture**: Webview with Rust backend + +**Pros**: +- ✅ Use any web framework (React, Vue, Svelte, etc.) +- ✅ Rapid UI development with web technologies +- ✅ Small binary size (uses system webview) +- ✅ Desktop support excellent (Windows, Linux, macOS) +- ✅ Mobile support coming (Tauri Mobile) +- ✅ Large ecosystem of web UI libraries +- ✅ Familiar to web developers +- ✅ Hot reload support + +**Cons**: +- ❌ Depends on system webview (consistency issues) +- ❌ Mobile support still in beta +- ❌ Not truly native look/feel +- ❌ Performance worse than native solutions +- ❌ Startup time slower (webview initialization) +- ❌ Requires web dev skills +- ❌ More complex build process + +**Best for**: Teams with web dev experience, if you want to use React/Vue/Svelte. + +**Startup time estimate**: 300-800ms (webview initialization) +**Binary size**: 1-3MB (uses system webview) + +--- + +### Option 6: Slint (Declarative UI) +**Language**: Slint language + Rust +**Architecture**: Declarative markup language + +**Pros**: +- ✅ True cross-platform (desktop, embedded, mobile coming) +- ✅ Declarative UI with .slint files +- ✅ Native rendering (no webview) +- ✅ Good performance +- ✅ Design tools available +- ✅ Small binary size +- ✅ Good documentation +- ✅ Business-backed (SixtyFPS GmbH) + +**Cons**: +- ❌ Mobile support experimental +- ❌ Smaller community +- ❌ Need to learn new markup language +- ❌ Less flexible than code-based solutions +- ❌ Dual licensing (GPL or commercial) + +**Best for**: If you want declarative UI with good tooling and don't mind learning new syntax. + +**Startup time estimate**: 100-250ms +**Binary size**: 2-4MB + +--- + +### Option 7: Flutter (Dart) +**Language**: Dart (not Rust!) +**Architecture**: Widget tree + +**Pros**: +- ✅ Best mobile support (iOS, Android) +- ✅ Very mature and stable +- ✅ Huge widget library +- ✅ Excellent documentation +- ✅ Great tooling and dev experience +- ✅ Desktop support good +- ✅ Beautiful UIs out of the box +- ✅ Fast startup on mobile + +**Cons**: +- ❌ **Not Rust!** (breaks our stack) +- ❌ Requires Dart FFI to call Rust backend +- ❌ Larger binary size (10-20MB) +- ❌ Different language/ecosystem +- ❌ More complex integration + +**Best for**: If mobile is top priority and you're willing to use Dart + Rust FFI. + +**Startup time estimate**: 200-400ms +**Binary size**: 10-20MB + +--- + +### Option 8: Native Platform UIs (Platform-specific) +**Language**: Rust + platform bindings +**Options**: gtk-rs (Linux), windows-rs (Windows), cacao (macOS), UIKit bindings (iOS), Android NDK + +**Pros**: +- ✅ True native look and feel per platform +- ✅ Best platform integration +- ✅ Smallest binaries per platform +- ✅ Fastest startup time +- ✅ Platform features "just work" + +**Cons**: +- ❌ **Separate codebase per platform** +- ❌ 5x development effort +- ❌ Hard to maintain consistency +- ❌ Need to learn each platform +- ❌ More testing required + +**Best for**: If native feel is paramount and you have resources for multiple codebases. + +**Startup time estimate**: 50-150ms (native) +**Binary size**: 1-3MB per platform + +--- + +## Frontend Framework Recommendation + +Based on your requirements (fast startup, cross-platform, potential for game-like polish): + +### Recommended: Start with **egui** for Phase 3 + +**Why egui?** +1. **Fastest time to market**: Rich widgets out of the box +2. **Good performance**: Fast startup, low overhead +3. **Cross-platform**: Desktop works great, mobile possible +4. **Simple integration**: Easy to connect to `bevy-tasks-core` +5. **Validate UX**: Test core app experience quickly +6. **Path forward**: Can always switch to Bevy later if you want game-like features + +### Alternative path: **Bevy** for unique polish + +**Choose Bevy if:** +- You want game-like animations from the start +- You're excited about building custom UI +- You value long-term flexibility over short-term speed +- You want a unique, polished look + +### Hybrid approach (Recommended) + +**Best of both worlds:** +1. Build Phase 3 MVP with **egui** (fast iteration) +2. Validate UX, backend API, and app concept +3. If you want more polish, rebuild with **Bevy** in Phase 6 +4. Backend stays the same (clean separation!) + +This de-risks the project while keeping options open. + +### Quick Decision Matrix + +| Framework | Startup | Binary | Mobile | Dev Speed | Polish Potential | Learning Curve | +|-----------|---------|--------|--------|-----------|-----------------|----------------| +| **Bevy** | ⚠️ Medium | ⚠️ Large | ✅ Good | ⚠️ Slow | ⭐⭐⭐⭐⭐ | Hard | +| **egui** | ✅ Fast | ✅ Small | ⚠️ OK | ✅ Fast | ⭐⭐⭐ | Easy | +| **Iced** | ✅ Fast | ✅ Small | ❌ Poor | ✅ Good | ⭐⭐⭐ | Medium | +| **Dioxus** | ⚠️ Medium | ⚠️ Medium | ⚠️ Webview | ✅ Fast | ⭐⭐ | Easy (if React) | +| **Tauri** | ❌ Slow | ✅ Small | ⚠️ Beta | ✅ Very Fast | ⭐⭐ | Easy (web) | +| **Slint** | ✅ Fast | ✅ Small | ⚠️ Exp | ⚠️ Medium | ⭐⭐⭐ | Medium | +| **Flutter** | ✅ Fast | ⚠️ Large | ⭐⭐⭐⭐⭐ | ✅ Very Fast | ⭐⭐⭐⭐ | Medium (Dart) | +| **Native** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ Very Slow | ⭐⭐⭐⭐ | Very Hard | + ## Dependencies -### Core Dependencies +### Workspace Structure (Cargo.toml) ```toml -[dependencies] -bevy = "0.16" +[workspace] +members = [ + "crates/bevy-tasks-core", + "crates/bevy-tasks-cli", + "crates/bevy-tasks-gui", +] +resolver = "2" + +[workspace.dependencies] +# Shared dependencies serde = { version = "1.0", features = ["derive"] } -serde_json = "1.0" -serde_yaml = "0.9" # For frontmatter parsing -pulldown-cmark = "0.9" # Markdown parsing uuid = { version = "1.0", features = ["serde", "v4"] } chrono = { version = "0.4", features = ["serde"] } -directories = "5.0" -tokio = { version = "1.0", features = ["full"] } anyhow = "1.0" +tokio = { version = "1.40", features = ["full"] } +``` + +### Core Library (bevy-tasks-core/Cargo.toml) +```toml +[package] +name = "bevy-tasks-core" +version = "0.1.0" +edition = "2024" + +[dependencies] +serde = { workspace = true } +serde_json = "1.0" +serde_yaml = "0.9" # YAML frontmatter parsing +pulldown-cmark = "0.12" # Markdown parsing +uuid = { workspace = true } +chrono = { workspace = true } +directories = "5.0" # Cross-platform paths +tokio = { workspace = true } +anyhow = { workspace = true } # WebDAV support -reqwest = { version = "0.11", features = ["json"] } -# Note: Evaluate dav-client alternatives +reqwest = { version = "0.12", features = ["json", "rustls-tls"] } +# TODO: Evaluate dav-client or implement custom WebDAV -# Credential storage (see Authentication Options) -keyring = "2.0" # Cross-platform keychain access +# Credential storage +keyring = "3.0" # Cross-platform keychain + +[dev-dependencies] +tempfile = "3.0" # For testing file operations +``` + +### CLI (bevy-tasks-cli/Cargo.toml) +```toml +[package] +name = "bevy-tasks-cli" +version = "0.1.0" +edition = "2024" + +[[bin]] +name = "bevy-tasks" +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 +anyhow = { workspace = true } +tokio = { workspace = true } +``` + +### GUI (bevy-tasks-gui/Cargo.toml) +```toml +[package] +name = "bevy-tasks-gui" +version = "0.1.0" +edition = "2024" + +[dependencies] +bevy-tasks-core = { path = "../bevy-tasks-core" } +anyhow = { workspace = true } + +# GUI framework - TBD based on chosen option +# Option 1: Bevy +# bevy = { version = "0.16", default-features = false, features = ["bevy_ui", "bevy_render", "bevy_winit"] } + +# Option 2: egui (Recommended for MVP) +# eframe = "0.31" +# egui = "0.31" + +# Option 3: Iced +# iced = { version = "0.13", features = ["tokio"] } + +# Option 4: Dioxus +# dioxus = "0.6" +# dioxus-desktop = "0.6" # Platform-specific [target.'cfg(target_os = "android")'.dependencies] @@ -410,8 +877,8 @@ keyring = "2.0" # Cross-platform keychain access ## Getting Started ### Prerequisites -- Rust 1.75+ (Bevy 0.16 requirement) -- Platform-specific tools: +- Rust 1.75+ (2024 edition) +- Platform-specific tools (for mobile builds later): - **iOS**: macOS + Xcode - **Android**: Android SDK + NDK @@ -421,87 +888,62 @@ keyring = "2.0" # Cross-platform keychain access git clone cd bevy-tasks -# Run desktop version -cargo run +# Build all workspace members +cargo build + +# Run tests for core library +cargo test -p bevy-tasks-core + +# Run CLI +cargo run -p bevy-tasks-cli -- --help +cargo run -p bevy-tasks-cli -- init ~/test-tasks + +# Run GUI (once implemented) +cargo run -p bevy-tasks-gui # Build for release -cargo build --release +cargo build --release -p bevy-tasks-cli +cargo build --release -p bevy-tasks-gui -# Run tests -cargo test +# Run all tests +cargo test --workspace +``` -# Build for Android -cargo apk build --release +### Development Workflow (Phase 1) -# Build for iOS (on macOS) -cargo build --target aarch64-apple-ios --release +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 ~/my-tasks +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. UI Framework: bevy_ui vs bevy_egui +### 1. Frontend Framework Choice -#### Option A: Pure bevy_ui -**Pros**: -- Native to Bevy, no additional dependencies -- Full control over rendering and styling -- Better performance (no intermediate UI layer) -- Fits Bevy's ECS paradigm perfectly -- More flexibility for game-like UX polish later -- Smaller binary size -- Consistent cross-platform look +**Status**: See "Frontend Framework Comparison" section above for detailed analysis. -**Cons**: -- More verbose, lower-level API -- Need to build complex widgets from scratch -- Text input handling requires more work -- Fewer built-in widgets -- Steeper learning curve for complex layouts -- More code to maintain - -**Best for**: If you want maximum performance, full control, and are willing to invest time building custom widgets. - -#### Option B: bevy_egui -**Pros**: -- Rich set of built-in widgets (text input, combo boxes, etc.) -- Immediate mode GUI is simple to reason about -- Rapid prototyping and iteration -- Good text editing support out of the box -- Mature ecosystem -- Less code for standard UI patterns -- Better accessibility features - -**Cons**: -- Additional dependency (~500KB+) -- Slight performance overhead -- Less control over rendering -- Immediate mode pattern conflicts with ECS -- Harder to achieve game-like polish -- Less Bevy-native feel -- More challenging to customize appearance - -**Best for**: If you want to ship quickly with standard UI widgets and don't need deep customization. - -#### Option C: Hybrid Approach -Use **bevy_ui** for primary interface (task lists, main views) and **bevy_egui** for complex forms and settings screens. - -**Pros**: -- Best of both worlds -- Use right tool for each job -- Fast development where needed, optimized where it matters - -**Cons**: -- Two UI systems to learn and maintain -- Increased binary size -- Inconsistent look without careful styling - -#### Recommendation -Start with **pure bevy_ui** for MVP. The task list UI is relatively simple (lists, buttons, text), and this gives you: -- Maximum performance for fast startup -- Foundation for future game-like polish -- Full control over mobile UX - -Reserve bevy_egui as a fallback if text editing becomes too complex to implement. +**Current Recommendation**: Start with **egui** for Phase 3 (fast MVP), optionally migrate to **Bevy** in Phase 6 for polish. --- @@ -630,6 +1072,6 @@ To be determined. --- -**Last Updated**: 2025-10-26 -**Document Version**: 1.1 -**Status**: Planning Phase +**Last Updated**: 2025-10-27 +**Document Version**: 2.0 +**Status**: Planning Phase - Backend/Frontend Separation Decided From f2025b11ab7026caef57eecf1a958c8e37d83d7d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 00:29:21 +0000 Subject: [PATCH 04/19] Simplify plan: finalize egui hybrid approach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed exploratory framework comparison details and consolidated the decision to use the hybrid approach: - Phase 3-5: egui for fast MVP development - Phase 6: Optional migration to Bevy for game-like polish - Backend (bevy-tasks-core) stays framework-agnostic Key changes: - Replaced 8-framework detailed comparison with concise decision - Updated GUI Cargo.toml to use egui (eframe + egui) - Simplified "Questions & Decisions" section (removed UI framework question) - Updated performance strategy for egui instead of Bevy - Updated startup sequence to reflect egui (< 200ms target) - Cleaned up Challenge 1 to be egui-specific The plan is now focused and ready for implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 361 +++++++++----------------------------------------------- 1 file changed, 56 insertions(+), 305 deletions(-) diff --git a/PLAN.md b/PLAN.md index d1904a1..ddb189b 100644 --- a/PLAN.md +++ b/PLAN.md @@ -273,23 +273,26 @@ pub trait Storage { #### Fast Startup Requirements 1. **Minimal initialization**: Load only essential systems -2. **Lazy UI rendering**: Render visible items first -3. **Background loading**: Load non-critical data after first frame -4. **Asset optimization**: Embed minimal assets, load rest async -5. **Incremental parsing**: Stream large data files +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 -1. Initialize Bevy minimal plugins (< 50ms) +#### Startup Sequence (egui GUI) +1. Initialize eframe window (< 50ms) 2. Load config from disk (< 20ms) -3. Render splash/empty state (first frame < 100ms) -4. Load task lists in background -5. Render tasks as they load -6. Start WebDAV sync (if configured) +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 -- Unload non-visible screens from memory +- Lazy load task lists (only load selected list) +- Stream markdown parsing for large files ## Feature Roadmap @@ -460,14 +463,15 @@ bevy-tasks sync --status ## Technical Challenges & Solutions -### Challenge 1: Fast Startup with Bevy -**Problem**: Bevy's plugin system can add overhead +### Challenge 1: Fast Startup with GUI +**Problem**: UI initialization can add overhead -**Solutions**: -- Use `MinimalPlugins` instead of `DefaultPlugins` -- Add only required plugins (rendering, input) -- Lazy-load audio, asset server if not needed immediately +**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 @@ -498,277 +502,40 @@ bevy-tasks sync --status - Users handle their own backups (external to app) - Migration can be done in-place by updating frontmatter -## Frontend Framework Comparison +## Frontend Framework Decision -Now that we have backend/frontend separation, we can evaluate multiple GUI framework options. The backend (`bevy-tasks-core`) is framework-agnostic. +**Decision Made**: Hybrid approach with **egui** for Phase 3, optional **Bevy** migration in Phase 6. -### Option 1: Bevy (Game Engine) -**Language**: Rust -**Architecture**: ECS (Entity Component System) +### Phase 3-5: egui (Immediate Mode GUI) -**Pros**: -- ✅ True cross-platform (Windows, Linux, macOS, iOS, Android, WASM) -- ✅ Excellent performance (60+ FPS easily) -- ✅ Future game-like polish and animations -- ✅ Active community and development -- ✅ Full control over rendering -- ✅ Single codebase for all platforms -- ✅ Fast startup possible with `MinimalPlugins` - -**Cons**: -- ❌ UI system is still maturing (bevy_ui improving but limited) -- ❌ More code required for standard widgets -- ❌ Steeper learning curve (ECS paradigm) -- ❌ Larger binary size (~5-10MB stripped) -- ❌ Text input handling requires extra work -- ❌ Not designed for traditional UIs - -**Best for**: If you want game-like polish, animations, and are willing to build custom UI components. - -**Startup time estimate**: 200-500ms -**Binary size**: 5-10MB (stripped) - ---- - -### Option 2: egui (Immediate Mode GUI) -**Language**: Rust -**Integration**: Standalone or with eframe - -**Pros**: -- ✅ True cross-platform (desktop, WASM, can run on mobile) -- ✅ Very simple API (immediate mode) -- ✅ Rich built-in widgets -- ✅ Excellent text editing support -- ✅ Small binary size (~2-3MB) -- ✅ Fast development iteration +**Why egui for MVP?** +- ✅ 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 -- ✅ Good performance -- ✅ Works with multiple backends (glow, wgpu) +- ✅ Simple immediate-mode API +- ✅ Cross-platform (desktop primary, mobile possible) +- ✅ Easy integration with `bevy-tasks-core` -**Cons**: -- ❌ Mobile support exists but less mature -- ❌ Immediate mode can be unusual coming from retained mode -- ❌ Less flexibility for custom animations -- ❌ Harder to achieve "game-like" polish -- ❌ Less native feel on each platform +**Trade-offs**: +- ⚠️ Less flexibility for custom animations +- ⚠️ Mobile support less mature (but improving) +- ⚠️ Not as "game-like" polish potential -**Best for**: Quick development, standard UI needs, if you don't need game-like features. +### Phase 6 (Optional): Migration to Bevy -**Startup time estimate**: 100-200ms -**Binary size**: 2-3MB (stripped) +**If you want game-like polish later:** +- ✅ Full control over animations and rendering +- ✅ Unique, polished look beyond standard apps +- ✅ Better 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. -### Option 3: Iced (Elm-inspired) -**Language**: Rust -**Architecture**: The Elm Architecture (TEA) - -**Pros**: -- ✅ Cross-platform (Windows, Linux, macOS, WASM) -- ✅ Declarative, reactive UI (similar to SwiftUI/Flutter) -- ✅ Clean architecture with clear state management -- ✅ Type-safe -- ✅ Good widget library -- ✅ Native-feeling widgets -- ✅ Async support built-in -- ✅ Medium binary size (~3-5MB) - -**Cons**: -- ❌ Mobile support experimental (iOS/Android not production-ready) -- ❌ Smaller community than egui or Bevy -- ❌ Still evolving (breaking changes possible) -- ❌ Limited animation capabilities -- ❌ Less documentation than mature frameworks - -**Best for**: If you like reactive/declarative UIs and primarily target desktop + WASM. - -**Startup time estimate**: 150-300ms -**Binary size**: 3-5MB (stripped) - ---- - -### Option 4: Dioxus (React-like) -**Language**: Rust -**Architecture**: Virtual DOM with React-like hooks - -**Pros**: -- ✅ Cross-platform (desktop, web, mobile via TUI or webview) -- ✅ React-like API (familiar to web devs) -- ✅ Hot reload support -- ✅ Component-based architecture -- ✅ Fast development -- ✅ Can target web with same code -- ✅ Active development - -**Cons**: -- ❌ Mobile support uses webview (not truly native) -- ❌ Still young and evolving -- ❌ Less mature than other options -- ❌ Performance not as good as native solutions -- ❌ Webview adds overhead on mobile - -**Best for**: Web developers wanting familiar patterns, prioritizing web deployment. - -**Startup time estimate**: 200-400ms (desktop), slower on mobile (webview) -**Binary size**: 4-8MB (includes webview on mobile) - ---- - -### Option 5: Tauri (Web Tech + Rust Backend) -**Language**: HTML/CSS/JavaScript (or any web framework) + Rust -**Architecture**: Webview with Rust backend - -**Pros**: -- ✅ Use any web framework (React, Vue, Svelte, etc.) -- ✅ Rapid UI development with web technologies -- ✅ Small binary size (uses system webview) -- ✅ Desktop support excellent (Windows, Linux, macOS) -- ✅ Mobile support coming (Tauri Mobile) -- ✅ Large ecosystem of web UI libraries -- ✅ Familiar to web developers -- ✅ Hot reload support - -**Cons**: -- ❌ Depends on system webview (consistency issues) -- ❌ Mobile support still in beta -- ❌ Not truly native look/feel -- ❌ Performance worse than native solutions -- ❌ Startup time slower (webview initialization) -- ❌ Requires web dev skills -- ❌ More complex build process - -**Best for**: Teams with web dev experience, if you want to use React/Vue/Svelte. - -**Startup time estimate**: 300-800ms (webview initialization) -**Binary size**: 1-3MB (uses system webview) - ---- - -### Option 6: Slint (Declarative UI) -**Language**: Slint language + Rust -**Architecture**: Declarative markup language - -**Pros**: -- ✅ True cross-platform (desktop, embedded, mobile coming) -- ✅ Declarative UI with .slint files -- ✅ Native rendering (no webview) -- ✅ Good performance -- ✅ Design tools available -- ✅ Small binary size -- ✅ Good documentation -- ✅ Business-backed (SixtyFPS GmbH) - -**Cons**: -- ❌ Mobile support experimental -- ❌ Smaller community -- ❌ Need to learn new markup language -- ❌ Less flexible than code-based solutions -- ❌ Dual licensing (GPL or commercial) - -**Best for**: If you want declarative UI with good tooling and don't mind learning new syntax. - -**Startup time estimate**: 100-250ms -**Binary size**: 2-4MB - ---- - -### Option 7: Flutter (Dart) -**Language**: Dart (not Rust!) -**Architecture**: Widget tree - -**Pros**: -- ✅ Best mobile support (iOS, Android) -- ✅ Very mature and stable -- ✅ Huge widget library -- ✅ Excellent documentation -- ✅ Great tooling and dev experience -- ✅ Desktop support good -- ✅ Beautiful UIs out of the box -- ✅ Fast startup on mobile - -**Cons**: -- ❌ **Not Rust!** (breaks our stack) -- ❌ Requires Dart FFI to call Rust backend -- ❌ Larger binary size (10-20MB) -- ❌ Different language/ecosystem -- ❌ More complex integration - -**Best for**: If mobile is top priority and you're willing to use Dart + Rust FFI. - -**Startup time estimate**: 200-400ms -**Binary size**: 10-20MB - ---- - -### Option 8: Native Platform UIs (Platform-specific) -**Language**: Rust + platform bindings -**Options**: gtk-rs (Linux), windows-rs (Windows), cacao (macOS), UIKit bindings (iOS), Android NDK - -**Pros**: -- ✅ True native look and feel per platform -- ✅ Best platform integration -- ✅ Smallest binaries per platform -- ✅ Fastest startup time -- ✅ Platform features "just work" - -**Cons**: -- ❌ **Separate codebase per platform** -- ❌ 5x development effort -- ❌ Hard to maintain consistency -- ❌ Need to learn each platform -- ❌ More testing required - -**Best for**: If native feel is paramount and you have resources for multiple codebases. - -**Startup time estimate**: 50-150ms (native) -**Binary size**: 1-3MB per platform - ---- - -## Frontend Framework Recommendation - -Based on your requirements (fast startup, cross-platform, potential for game-like polish): - -### Recommended: Start with **egui** for Phase 3 - -**Why egui?** -1. **Fastest time to market**: Rich widgets out of the box -2. **Good performance**: Fast startup, low overhead -3. **Cross-platform**: Desktop works great, mobile possible -4. **Simple integration**: Easy to connect to `bevy-tasks-core` -5. **Validate UX**: Test core app experience quickly -6. **Path forward**: Can always switch to Bevy later if you want game-like features - -### Alternative path: **Bevy** for unique polish - -**Choose Bevy if:** -- You want game-like animations from the start -- You're excited about building custom UI -- You value long-term flexibility over short-term speed -- You want a unique, polished look - -### Hybrid approach (Recommended) - -**Best of both worlds:** -1. Build Phase 3 MVP with **egui** (fast iteration) -2. Validate UX, backend API, and app concept -3. If you want more polish, rebuild with **Bevy** in Phase 6 -4. Backend stays the same (clean separation!) - -This de-risks the project while keeping options open. - -### Quick Decision Matrix - -| Framework | Startup | Binary | Mobile | Dev Speed | Polish Potential | Learning Curve | -|-----------|---------|--------|--------|-----------|-----------------|----------------| -| **Bevy** | ⚠️ Medium | ⚠️ Large | ✅ Good | ⚠️ Slow | ⭐⭐⭐⭐⭐ | Hard | -| **egui** | ✅ Fast | ✅ Small | ⚠️ OK | ✅ Fast | ⭐⭐⭐ | Easy | -| **Iced** | ✅ Fast | ✅ Small | ❌ Poor | ✅ Good | ⭐⭐⭐ | Medium | -| **Dioxus** | ⚠️ Medium | ⚠️ Medium | ⚠️ Webview | ✅ Fast | ⭐⭐ | Easy (if React) | -| **Tauri** | ❌ Slow | ✅ Small | ⚠️ Beta | ✅ Very Fast | ⭐⭐ | Easy (web) | -| **Slint** | ✅ Fast | ✅ Small | ⚠️ Exp | ⚠️ Medium | ⭐⭐⭐ | Medium | -| **Flutter** | ✅ Fast | ⚠️ Large | ⭐⭐⭐⭐⭐ | ✅ Very Fast | ⭐⭐⭐⭐ | Medium (Dart) | -| **Native** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ❌ Very Slow | ⭐⭐⭐⭐ | Very Hard | +This approach de-risks the project: validate the concept with egui, then optionally invest in custom polish with Bevy if the app takes off. ## Dependencies @@ -851,27 +618,19 @@ edition = "2024" bevy-tasks-core = { path = "../bevy-tasks-core" } anyhow = { workspace = true } -# GUI framework - TBD based on chosen option -# Option 1: Bevy +# egui for Phase 3-5 +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"] } -# Option 2: egui (Recommended for MVP) -# eframe = "0.31" -# egui = "0.31" - -# Option 3: Iced -# iced = { version = "0.13", features = ["tokio"] } - -# Option 4: Dioxus -# dioxus = "0.6" -# dioxus-desktop = "0.6" - # Platform-specific [target.'cfg(target_os = "android")'.dependencies] -# Android-specific deps +# Android-specific deps (Phase 5) [target.'cfg(target_os = "ios")'.dependencies] -# iOS-specific deps +# iOS-specific deps (Phase 5) ``` ## Getting Started @@ -939,15 +698,7 @@ cargo run ## Questions & Decisions -### 1. Frontend Framework Choice - -**Status**: See "Frontend Framework Comparison" section above for detailed analysis. - -**Current Recommendation**: Start with **egui** for Phase 3 (fast MVP), optionally migrate to **Bevy** in Phase 6 for polish. - ---- - -### 2. Authentication Options for WebDAV +### 1. Authentication for WebDAV Sync #### Option A: Platform Keychain/Keyring **Implementation**: Use `keyring` crate for cross-platform credential storage @@ -1073,5 +824,5 @@ To be determined. --- **Last Updated**: 2025-10-27 -**Document Version**: 2.0 -**Status**: Planning Phase - Backend/Frontend Separation Decided +**Document Version**: 2.1 +**Status**: Ready to Implement - egui Hybrid Approach Confirmed From 774b88423637ac6e42eb39832521063c0c653df8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 00:36:23 +0000 Subject: [PATCH 05/19] Update storage strategy: user always selects folder location MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed from opaque platform-specific defaults to user-controlled storage: Before: - Default to hidden platform directories (%APPDATA%, ~/.local/share, etc.) - User could optionally select custom folder After: - User MUST select folder on first run (no hidden defaults) - Full transparency and control over data location - Examples: ~/Documents/Tasks, ~/Dropbox/Tasks, etc. Key changes: - CLI init requires folder path argument - GUI shows folder picker on first launch - Mobile prompts for folder location with suggestions - App config (theme, window size) still in platform-specific location - Task data always in user-visible, user-controlled folder Benefits: - Users can easily find and backup their data - Works seamlessly with cloud sync (Dropbox, iCloud, OneDrive) - Can use with other tools (Obsidian, VS Code) - Git-friendly for version control - Multiple task vaults possible (work/personal) - No lock-in, no hidden data Updated: - Storage strategy section - AppConfig model (local_path is required, not optional) - CLI examples (init requires path) - First run experience description - Repository API (takes tasks_folder directly) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 76 +++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 27 deletions(-) diff --git a/PLAN.md b/PLAN.md index ddb189b..1f7b1bc 100644 --- a/PLAN.md +++ b/PLAN.md @@ -109,12 +109,14 @@ TaskList { } AppConfig { - storage_type: StorageType, // Local or WebDAV - local_path: Option, - webdav_url: Option, + // 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, } ``` @@ -197,8 +199,8 @@ pub struct TaskRepository { } impl TaskRepository { - pub fn new(config: Config) -> Result; - pub fn init(path: PathBuf) -> Result; + pub fn new(tasks_folder: PathBuf) -> Result; + pub fn init(tasks_folder: PathBuf) -> Result; // Task operations pub fn create_task(&mut self, list_id: Uuid, task: Task) -> Result; @@ -229,19 +231,23 @@ pub trait Storage { ### Storage Strategy #### Local Storage -- **Location**: User-selectable folder OR platform-specific app data directory - - Windows: `%APPDATA%/bevy-tasks/` (default) - - Linux: `~/.local/share/bevy-tasks/` (default) - - macOS: `~/Library/Application Support/bevy-tasks/` (default) - - iOS: App sandbox documents directory - - Android: Internal storage app directory - - User can select any folder with read/write permissions +- **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**: ``` - data/ + ~/Documents/Tasks/ # User-selected folder ├── .bevy-tasks/ - │ ├── config.json # App configuration │ └── metadata.json # List ordering, sync state ├── My Tasks/ # Task list folder │ ├── Buy groceries.md @@ -253,13 +259,20 @@ pub trait Storage { └── Team meeting prep.md ``` -**Benefits of Markdown Format**: -- Human-readable and editable in any text editor -- Compatible with Obsidian, Logseq, and other markdown tools -- Easy to version control (git-friendly) -- Future-proof format -- Enables external editing and scripting -- Natural organization with folders +**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 @@ -317,10 +330,19 @@ pub trait Storage { **CLI Example**: ```bash -bevy-tasks init ~/my-tasks +# 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) @@ -358,7 +380,7 @@ bevy-tasks sync --status - [ ] Basic task list view - [ ] Create/edit/delete tasks - [ ] Mark tasks complete -- [ ] Settings screen (storage location, WebDAV config) +- [ ] Settings screen (change folder location, WebDAV config) - [ ] Desktop support (Windows, Linux, macOS) - [ ] Sync status indicators @@ -379,7 +401,7 @@ bevy-tasks sync --status - [ ] Rich markdown editor for task notes - [ ] Drag & drop reordering - [ ] Move tasks between lists -- [ ] Folder picker for custom storage +- [ ] Change storage folder location in settings - [ ] Keyboard shortcuts - [ ] Search functionality @@ -679,7 +701,7 @@ cargo test --watch # with cargo-watch 2. **Build CLI to test backend**: ```bash cd crates/bevy-tasks-cli -cargo run -- init ~/my-tasks +cargo run -- init ~/Documents/TestTasks cargo run -- add "Test task" cargo run -- list ``` @@ -824,5 +846,5 @@ To be determined. --- **Last Updated**: 2025-10-27 -**Document Version**: 2.1 -**Status**: Ready to Implement - egui Hybrid Approach Confirmed +**Document Version**: 2.2 +**Status**: Ready to Implement - User-Controlled Storage From 075b7bb3341df4ccd5540f967ed5551ce25b1bbd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 00:40:04 +0000 Subject: [PATCH 06/19] Reprioritize mobile support and add Google Tasks importer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major roadmap changes: 1. Mobile Support Moved Up (Phase 4 instead of Phase 5): - Get iOS/Android builds working early, even with simple test UI - Validates cross-platform architecture ASAP - Foundation for future mobile polish - egui supports mobile, so we can test early New Phase Structure: - Phase 1: Core Library & CLI MVP - Phase 2: WebDAV Sync (Backend + CLI) - Phase 3: GUI MVP (Desktop) - Phase 4: Mobile Basic Support (NEW - prioritized) - Phase 5: GUI Advanced Features (Desktop + Mobile) - Phase 6: Mobile Polish & Platform Features - Phase 7: Advanced Features & Imports 2. Google Tasks Importer Added (Phase 7): - Migrate users from Google Tasks - Import tasks, lists, due dates, notes - Easy onboarding for existing Google Tasks users 3. Additional Phase 7 Features: - Tags and custom fields - Bulk operations - Calendar integration - Email to task - Voice input - Collaboration features Benefits of early mobile: - De-risk mobile builds early in development - Test cross-platform code paths sooner - Allows for mobile-specific feedback early - Can dogfood on mobile while building desktop features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 128 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 84 insertions(+), 44 deletions(-) diff --git a/PLAN.md b/PLAN.md index 1f7b1bc..61408e4 100644 --- a/PLAN.md +++ b/PLAN.md @@ -373,10 +373,8 @@ bevy-tasks sync --status ### Phase 3: GUI MVP (Desktop) **Goal**: Build graphical interface on desktop platforms -**Frontend Decision**: Choose frontend framework (see Frontend Comparison section) - **Features**: -- [ ] GUI framework integration +- [ ] egui framework integration - [ ] Basic task list view - [ ] Create/edit/delete tasks - [ ] Mark tasks complete @@ -390,8 +388,31 @@ bevy-tasks sync --status - Clean, minimal UI - Feature parity with CLI -### Phase 4: GUI Advanced Features (Desktop) -**Goal**: Feature parity with Google Tasks +### 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) @@ -399,53 +420,63 @@ bevy-tasks sync --status - [ ] Subtasks support - [ ] Due dates with date picker - [ ] Rich markdown editor for task notes -- [ ] Drag & drop reordering +- [ ] Drag & drop reordering (desktop) +- [ ] Swipe gestures (mobile) - [ ] Move tasks between lists - [ ] Change storage folder location in settings -- [ ] Keyboard shortcuts +- [ ] Keyboard shortcuts (desktop) - [ ] Search functionality +- [ ] Pull-to-refresh (mobile) **Deliverables**: -- Full-featured desktop task manager -- Polished UX -- Keyboard-driven workflow +- Full-featured task manager on all platforms +- Polished UX on desktop +- Touch-optimized UX on mobile +- Consistent feature set -### Phase 5: Mobile Support -**Goal**: Deploy to iOS and Android +### Phase 6: Mobile Polish & Platform-Specific Features +**Goal**: Native mobile experience and platform integration **Features**: -- [ ] Touch-optimized UI -- [ ] iOS build pipeline -- [ ] Android build pipeline -- [ ] Mobile-specific UX (swipe gestures, pull-to-refresh) - [ ] Background sync on mobile -- [ ] Mobile file system integration -- [ ] Share extension (share to tasks) -- [ ] Native mobile feel +- [ ] 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**: -- Working iOS app -- Working Android app -- Consistent UX across mobile and desktop +- Native-feeling mobile apps +- Deep platform integration +- Mobile-specific features -### Phase 6: Polish & Advanced 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 -- [ ] Advanced animations and transitions (if using Bevy) - [ ] Full-text search across tasks - [ ] Filters and smart lists - [ ] Task templates - [ ] Recurring tasks - [ ] Statistics and insights -- [ ] Export/import (backup) +- [ ] Tags and custom fields +- [ ] Export/import (backup/restore) +- [ ] Bulk operations +- [ ] Advanced animations (consider Bevy migration) - [ ] Plugin system for extensions (optional) -- [ ] Game-like achievements (optional, if using Bevy) +- [ ] 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 @@ -466,15 +497,15 @@ bevy-tasks sync --status ### Build & Release - **CI/CD**: GitHub Actions for all platforms -- **Initial Distribution**: +- **Initial Distribution** (Phases 3-4): - **Desktop**: Direct downloads and sideloading - Linux: AppImage, .tar.gz - macOS: DMG - Windows: MSI, portable .exe - - **Mobile**: Sideloading only - - iOS: .ipa for TestFlight/direct install - - Android: .apk -- **Future Distribution Channels** (Phase 5+): + - **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 @@ -499,10 +530,13 @@ bevy-tasks sync --status **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 early and often on real devices -- Follow platform guidelines (iOS HIG, Material Design) -- Use platform-specific file pickers and sharing +- 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 @@ -528,36 +562,42 @@ bevy-tasks sync --status **Decision Made**: Hybrid approach with **egui** for Phase 3, optional **Bevy** migration in Phase 6. -### Phase 3-5: egui (Immediate Mode GUI) +### Phase 3-6: egui (Immediate Mode GUI) -**Why egui for MVP?** +**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 primary, mobile possible) +- ✅ 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 support less mature (but improving) +- ⚠️ Mobile UX requires extra work for touch optimization - ⚠️ Not as "game-like" polish potential -### Phase 6 (Optional): Migration to Bevy +**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 -**If you want game-like polish later:** +### 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 -- ✅ Better mobile support (iOS/Android) +- ✅ 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, then optionally invest in custom polish with Bevy if the app takes off. +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 @@ -846,5 +886,5 @@ To be determined. --- **Last Updated**: 2025-10-27 -**Document Version**: 2.2 -**Status**: Ready to Implement - User-Controlled Storage +**Document Version**: 2.3 +**Status**: Ready to Implement - Mobile-First, User-Controlled Storage From 4bca034ba4049264ede37251bf28a48d239b6aa1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 16:42:52 +0000 Subject: [PATCH 07/19] 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 From 90e7e70ea0f2bf7827ec0e2bce7d7801b0ed1a55 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 16:48:03 +0000 Subject: [PATCH 08/19] Move Development Guidelines and Resources before roadmap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorganized document structure: Before: 1. Vision 2. Phase 1-7 3. Development Guidelines 4. Resources After: 1. Vision 2. Development Guidelines 3. Resources 4. Phase 1-7 Benefits: - Guidelines available as reference from the start - Performance budgets visible before implementation - Testing strategy known upfront - Resources accessible throughout all phases - More logical flow for developers starting the project 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 64 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/PLAN.md b/PLAN.md index 57415d3..fb7e594 100644 --- a/PLAN.md +++ b/PLAN.md @@ -19,6 +19,39 @@ A **local-first, cross-platform tasks application** inspired by Google Tasks. Bu --- +## 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/) +- [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 importer reference) + +--- + ## Phase 1: Core Library & CLI MVP **Goal**: Build and validate the backend with a functional CLI @@ -716,37 +749,6 @@ If you want game-like polish after Phase 7: --- -## 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/) -- [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 importer reference) - ## License To be determined. From 021e532900d2ec55a2238ad29911f273ea841bac Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 27 Oct 2025 16:51:50 +0000 Subject: [PATCH 09/19] Set license to GPL v3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The project will be licensed under GNU General Public License v3.0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/PLAN.md b/PLAN.md index fb7e594..feb9a79 100644 --- a/PLAN.md +++ b/PLAN.md @@ -751,7 +751,9 @@ If you want game-like polish after Phase 7: ## License -To be determined. +[GNU General Public License v3.0 (GPL-3.0)](https://www.gnu.org/licenses/gpl-3.0.en.html) + +This project is free and open-source software licensed under GPL v3. --- From 123ebf9b430a08aac0e6f77c3685386c19648da2 Mon Sep 17 00:00:00 2001 From: SteelDynamite Date: Sun, 2 Nov 2025 10:25:49 -0800 Subject: [PATCH 10/19] Revise PLAN.md by removing development guidelines Removed development guidelines and performance budgets sections. --- PLAN.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/PLAN.md b/PLAN.md index feb9a79..0b84d3f 100644 --- a/PLAN.md +++ b/PLAN.md @@ -6,11 +6,8 @@ A **local-first, cross-platform tasks application** inspired by Google Tasks. Bu **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 **Data Format**: Tasks stored as markdown files with YAML frontmatter (Obsidian-compatible) **Storage**: User selects folder location (e.g., `~/Documents/Tasks`, `~/Dropbox/Tasks`) @@ -19,30 +16,6 @@ A **local-first, cross-platform tasks application** inspired by Google Tasks. Bu --- -## 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/) From fd04624677b1a842b6634139c811433dc41b8970 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 2 Nov 2025 18:38:13 +0000 Subject: [PATCH 11/19] Update storage structure: per-list metadata and cleaner naming MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed metadata structure for better organization: OLD: ~/Tasks/.bevy-tasks/metadata.json (global) ~/Tasks/My Tasks/ (no list metadata) NEW: ~/Tasks/.metadata.json (global: list order, last opened) ~/Tasks/My Tasks/.listdata.json (per-list: task order, id, timestamps) Key improvements: 1. Task ordering in .listdata.json - reordering only updates one file 2. Removed position field from task frontmatter 3. List metadata stays with the list (portable) 4. Cleaner naming: .metadata.json and .listdata.json 5. No nested hidden folders Updated: - File system structure diagram - Data models (removed position from Task and TaskList) - Added note about position being in .listdata.json - Added reorder_task() and get_task_order() to API - Updated AppConfig comment Benefits: - Reordering tasks = single file update - Moving/copying lists preserves metadata - WebDAV sync naturally groups data - Cleaner file structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/PLAN.md b/PLAN.md index 0b84d3f..c4e2a9c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -62,7 +62,6 @@ due: 2025-11-15T14:00:00Z created: 2025-10-26T10:00:00Z updated: 2025-10-26T12:30:00Z parent: 550e8400-e29b-41d4-a716-446655440001 -position: 1 tags: [work, urgent] --- @@ -73,6 +72,8 @@ Task description and notes go here in **markdown** format. - Links, etc. ``` +**Note**: No `position` field in frontmatter - task ordering is stored in the list's `.listdata.json` file. This means reordering tasks only requires updating one file. + **In-Memory Model**: ```rust Task { @@ -84,8 +85,8 @@ Task { created_at: DateTime, updated_at: DateTime, parent_id: Option, - position: i32, tags: Vec, + // Note: position stored in .listdata.json, not in frontmatter } TaskList { @@ -94,7 +95,7 @@ TaskList { tasks: Vec, created_at: DateTime, updated_at: DateTime, - position: i32, + // Note: task_order stored in .listdata.json, not in memory model } AppConfig { @@ -108,18 +109,48 @@ AppConfig { ``` ~/Documents/Tasks/ # User-selected folder -├── .bevy-tasks/ -│ └── metadata.json # List ordering, sync state +├── .metadata.json # Global: list ordering, last opened list ├── My Tasks/ # Task list folder +│ ├── .listdata.json # List metadata: task order, id, timestamps │ ├── Buy groceries.md │ ├── Call dentist.md │ └── Project X/ # Subtask folder (optional) │ └── Design mockup.md └── Work/ # Another task list + ├── .listdata.json ├── Review PRs.md └── Team meeting prep.md ``` +**`.metadata.json` (root level)**: +```json +{ + "version": 1, + "list_order": ["list-uuid-1", "list-uuid-2"], + "last_opened_list": "list-uuid-1" +} +``` + +**`.listdata.json` (per list)**: +```json +{ + "id": "list-uuid-1", + "created_at": "2025-10-26T10:00:00Z", + "updated_at": "2025-10-27T14:30:00Z", + "task_order": [ + "task-uuid-1", + "task-uuid-2", + "task-uuid-3" + ] +} +``` + +**Benefits**: +- **Ordering in list metadata**: Reordering tasks only touches `.listdata.json` +- **Portable lists**: Copy/move a list folder and its metadata stays with it +- **Clean structure**: No nested hidden folders, just hidden files +- **WebDAV-friendly**: Syncing a list syncs its metadata naturally + **App Configuration** (separate from task data): - Windows: `%APPDATA%/bevy-tasks/config.json` - Linux: `~/.config/bevy-tasks/config.json` @@ -147,6 +178,10 @@ 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<()>; + + // Task ordering (modifies .listdata.json) + pub fn reorder_task(&mut self, list_id: Uuid, task_id: Uuid, new_position: usize) -> Result<()>; + pub fn get_task_order(&self, list_id: Uuid) -> Result>; } pub trait Storage { @@ -293,10 +328,11 @@ Add WebDAV support to `bevy-tasks-core`: ```rust // Update AppConfig AppConfig { - local_path: PathBuf, + local_path: PathBuf, // User-selected tasks folder (required) webdav_url: Option, webdav_credentials: Option, last_sync: Option, + // Note: list_order and last_opened_list now in .metadata.json at root of tasks folder // ... } From 71619eddf91344e3a5f956fc45938df1e535fb49 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 2 Nov 2025 18:41:33 +0000 Subject: [PATCH 12/19] Simplify Phase 1: remove tags and move theme to GUI phase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cleaned up data model and configuration scope: REMOVED: - Tags field from Task model (out of scope, may never be needed) - Tags from frontmatter example - Tags from Phase 7 features - Theme from Phase 1 AppConfig (not needed until GUI) MOVED: - Theme configuration to Phase 3 (when GUI is introduced) - Added updated AppConfig in Phase 3 showing theme, window_size, last_opened_list Phase 1 now focuses on core essentials: - Task CRUD operations - Markdown file I/O - Basic data model (id, status, due_date, parent_id) - CLI functionality Benefits: - Simpler Phase 1 implementation - Less upfront complexity - Theme configuration appears when it's actually used (GUI) - Tags can be added later if needed (or never) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/PLAN.md b/PLAN.md index c4e2a9c..25edbdf 100644 --- a/PLAN.md +++ b/PLAN.md @@ -62,7 +62,6 @@ due: 2025-11-15T14:00:00Z created: 2025-10-26T10:00:00Z updated: 2025-10-26T12:30:00Z parent: 550e8400-e29b-41d4-a716-446655440001 -tags: [work, urgent] --- Task description and notes go here in **markdown** format. @@ -84,8 +83,7 @@ Task { due_date: Option, // From frontmatter created_at: DateTime, updated_at: DateTime, - parent_id: Option, - tags: Vec, + parent_id: Option, // For subtasks // Note: position stored in .listdata.json, not in frontmatter } @@ -100,8 +98,7 @@ TaskList { AppConfig { local_path: PathBuf, // User-selected tasks folder (required) - theme: Theme, - last_opened_list: Option, + // Note: theme and UI preferences added in Phase 3 (GUI) } ``` @@ -332,8 +329,7 @@ AppConfig { webdav_url: Option, webdav_credentials: Option, last_sync: Option, - // Note: list_order and last_opened_list now in .metadata.json at root of tasks folder - // ... + // Note: list_order and last_opened_list in .metadata.json at root of tasks folder } // Add sync methods to TaskRepository @@ -455,6 +451,21 @@ crates/bevy-tasks-gui/ - No default hidden directories - Remember choice in app config +#### App Configuration (Phase 3+) + +**Update AppConfig** to include UI preferences: +```rust +AppConfig { + local_path: PathBuf, // From Phase 1 + webdav_url: Option, // From Phase 2 + webdav_credentials: Option, + last_sync: Option, + theme: Theme, // NEW: light/dark mode + window_size: Option<(u32, u32)>, // NEW: remember window size + last_opened_list: Option, // NEW: restore last view +} +``` + ### Dependencies **bevy-tasks-gui/Cargo.toml**: @@ -621,7 +632,7 @@ mod android { - [ ] Move tasks between lists - [ ] Change storage folder location in settings - [ ] Search functionality -- [ ] Themes (light/dark mode) +- [ ] Theme selection (light/dark mode) #### Desktop-Specific - [ ] Drag & drop reordering @@ -702,7 +713,6 @@ mod android { - [ ] 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) From eb6bb932f7b4d164245905d16e0b91f0808cb63e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 2 Nov 2025 18:49:02 +0000 Subject: [PATCH 13/19] Add dual sort modes: manual ordering and by due date MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enhanced task ordering with two sort options: 1. Manual Ordering (default): - User can drag/drop to reorder tasks - Order stored in task_order array in .listdata.json - Only manual changes update the file 2. By Due Date: - Tasks automatically sorted by due_date field - Tasks without due dates appear at end - task_order array ignored when in this mode Changes: - Added sort_order field to .listdata.json ("manual" or "by_due_date") - Added SortOrder enum to TaskList model - Clarified that Vec order depends on sort preference - Added set_sort_order() and get_sort_order() to repository API - Added CLI sort command to switch between modes - Removed confusing comment about .listdata.json being "in-memory" Example .listdata.json: { "sort_order": "manual", "task_order": ["uuid-1", "uuid-2", "uuid-3"] } CLI usage: bevy-tasks sort manual --list "Work" bevy-tasks sort by-due-date --list "Personal" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/PLAN.md b/PLAN.md index 25edbdf..edd5d96 100644 --- a/PLAN.md +++ b/PLAN.md @@ -90,10 +90,15 @@ Task { TaskList { id: Uuid, title: String, // Derived from folder name - tasks: Vec, + tasks: Vec, // Ordered according to sort_order preference created_at: DateTime, updated_at: DateTime, - // Note: task_order stored in .listdata.json, not in memory model + sort_order: SortOrder, // How to sort: Manual or ByDueDate +} + +enum SortOrder { + Manual, // Use task_order from .listdata.json + ByDueDate, // Sort by due_date field (tasks without due dates at end) } AppConfig { @@ -134,6 +139,7 @@ AppConfig { "id": "list-uuid-1", "created_at": "2025-10-26T10:00:00Z", "updated_at": "2025-10-27T14:30:00Z", + "sort_order": "manual", "task_order": [ "task-uuid-1", "task-uuid-2", @@ -142,8 +148,15 @@ AppConfig { } ``` +**Sort Order Options**: +- `"manual"` - Tasks ordered by hand (uses `task_order` array) +- `"by_due_date"` - Tasks automatically sorted by due date (tasks without due dates appear at end) + +When `sort_order` is `"manual"`, the `task_order` array defines the sequence. When `sort_order` is `"by_due_date"`, tasks are sorted dynamically and `task_order` is ignored. + **Benefits**: -- **Ordering in list metadata**: Reordering tasks only touches `.listdata.json` +- **Two sort modes**: Manual ordering or automatic by due date +- **Ordering in list metadata**: Changing manual order only touches `.listdata.json` - **Portable lists**: Copy/move a list folder and its metadata stays with it - **Clean structure**: No nested hidden folders, just hidden files - **WebDAV-friendly**: Syncing a list syncs its metadata naturally @@ -179,6 +192,10 @@ impl TaskRepository { // Task ordering (modifies .listdata.json) pub fn reorder_task(&mut self, list_id: Uuid, task_id: Uuid, new_position: usize) -> Result<()>; pub fn get_task_order(&self, list_id: Uuid) -> Result>; + + // Sort preference (modifies .listdata.json) + pub fn set_sort_order(&mut self, list_id: Uuid, sort_order: SortOrder) -> Result<()>; + pub fn get_sort_order(&self, list_id: Uuid) -> Result; } pub trait Storage { @@ -262,6 +279,8 @@ tokio = { workspace = true } - [ ] CLI: `complete` command (mark done) - [ ] CLI: `delete` command (remove tasks) - [ ] CLI: `edit` command (modify tasks) +- [ ] Two sort modes: manual ordering and by due date +- [ ] CLI: `sort` command (switch between manual/by-due-date) - [ ] Comprehensive unit and integration tests (>80% coverage) ### CLI Usage Examples @@ -283,6 +302,10 @@ bevy-tasks delete # Change folder location later bevy-tasks config set-folder ~/new/location + +# Sort order +bevy-tasks sort manual --list "Work" +bevy-tasks sort by-due-date --list "Personal" ``` ### Deliverables From f472ed5f5738769005824c739ab74b81717368bd Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Nov 2025 10:20:18 +0000 Subject: [PATCH 14/19] Revise PLAN.md by removing development guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up data model and remove unnecessary notes: 1. Simplified TaskStatus: - Only two states: Backlog and Completed - Removed in-progress, not-started complexity - Clearer, simpler model 2. Removed unnecessary comments: - "Note: position stored in .listdata.json" (obvious from context) - "Note: theme and UI preferences added in Phase 3" (unnecessary) 3. Removed subtask folder example: - Already have parent_id for subtask relationships - No need to show nested folder structure - Keeps file structure example simple 4. Simplified AppConfig in Phase 1: - Just local_path, no extra comments Changes keep the plan focused and remove noise. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/PLAN.md b/PLAN.md index edd5d96..b70c039 100644 --- a/PLAN.md +++ b/PLAN.md @@ -57,7 +57,7 @@ Tasks are stored as individual `.md` files with YAML frontmatter: ```markdown --- id: 550e8400-e29b-41d4-a716-446655440000 -status: in-progress +status: backlog due: 2025-11-15T14:00:00Z created: 2025-10-26T10:00:00Z updated: 2025-10-26T12:30:00Z @@ -73,18 +73,26 @@ Task description and notes go here in **markdown** format. **Note**: No `position` field in frontmatter - task ordering is stored in the list's `.listdata.json` file. This means reordering tasks only requires updating one file. +**TaskStatus values**: +- `backlog` - Task not yet completed +- `completed` - Task is done + **In-Memory Model**: ```rust Task { id: Uuid, title: String, // Derived from filename notes: String, // Markdown content - status: TaskStatus, // From frontmatter - due_date: Option, // From frontmatter + status: TaskStatus, // Backlog or Completed + due_date: Option, created_at: DateTime, updated_at: DateTime, parent_id: Option, // For subtasks - // Note: position stored in .listdata.json, not in frontmatter +} + +enum TaskStatus { + Backlog, // Not yet completed + Completed, // Done } TaskList { @@ -102,8 +110,7 @@ enum SortOrder { } AppConfig { - local_path: PathBuf, // User-selected tasks folder (required) - // Note: theme and UI preferences added in Phase 3 (GUI) + local_path: PathBuf, } ``` @@ -115,9 +122,7 @@ AppConfig { ├── My Tasks/ # Task list folder │ ├── .listdata.json # List metadata: task order, id, timestamps │ ├── Buy groceries.md -│ ├── Call dentist.md -│ └── Project X/ # Subtask folder (optional) -│ └── Design mockup.md +│ └── Call dentist.md └── Work/ # Another task list ├── .listdata.json ├── Review PRs.md From f51d1251bb655ba681f5f8fc908e3c46a991eb25 Mon Sep 17 00:00:00 2001 From: SteelDynamite Date: Mon, 3 Nov 2025 13:07:03 -0800 Subject: [PATCH 15/19] Refine task description and sorting order Updated task structure and sorting logic in PLAN.md. --- PLAN.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/PLAN.md b/PLAN.md index b70c039..5e8f434 100644 --- a/PLAN.md +++ b/PLAN.md @@ -71,8 +71,6 @@ Task description and notes go here in **markdown** format. - Links, etc. ``` -**Note**: No `position` field in frontmatter - task ordering is stored in the list's `.listdata.json` file. This means reordering tasks only requires updating one file. - **TaskStatus values**: - `backlog` - Task not yet completed - `completed` - Task is done @@ -82,7 +80,7 @@ Task description and notes go here in **markdown** format. Task { id: Uuid, title: String, // Derived from filename - notes: String, // Markdown content + description: String, // Markdown content status: TaskStatus, // Backlog or Completed due_date: Option, created_at: DateTime, @@ -106,7 +104,7 @@ TaskList { enum SortOrder { Manual, // Use task_order from .listdata.json - ByDueDate, // Sort by due_date field (tasks without due dates at end) + ByDueDate, // Group by due_date, then sort by task_order within groups } AppConfig { From d1258e78640df2a082524b041a6a376c14f144b6 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Nov 2025 21:09:42 +0000 Subject: [PATCH 16/19] Add repeating tasks feature to Phase 7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added detailed repeating tasks functionality to Advanced Features: How it works: - When a repeating task is completed, it automatically: 1. Returns to backlog status 2. Updates due date by specified interval Supported intervals: - daily, weekly, monthly, yearly - Custom intervals (e.g., "every 3 days") - Optional end date or repetition limit Frontmatter fields: - repeat: "daily" | "weekly" | "monthly" | "yearly" | "every N days/weeks/months" - repeat_until: (optional) end date for repetitions Example use cases: - Daily standup notes - Weekly review tasks - Monthly bill payments - Quarterly reports This is a Phase 7 feature as it requires background processing to check completed tasks and reset them based on intervals. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/PLAN.md b/PLAN.md index 5e8f434..0e5bd1d 100644 --- a/PLAN.md +++ b/PLAN.md @@ -739,7 +739,12 @@ mod android { - [ ] Easy onboarding for Google Tasks users #### Advanced Task Management -- [ ] Recurring tasks (daily, weekly, monthly, custom) +- [ ] **Repeating tasks** (tasks that automatically uncomplete and reschedule) + - When completed, task automatically returns to backlog + - Due date updates by specified interval (e.g., +1 day, +1 week, +1 month) + - Intervals: daily, weekly, monthly, yearly, custom (e.g., "every 3 days") + - Optional: limit number of repetitions or end date + - Stored in frontmatter: `repeat: "daily"`, `repeat_until: "2026-01-01"` - [ ] Task templates (save common tasks) - [ ] Bulk operations (select multiple, bulk edit) - [ ] Full-text search across all tasks From e1b46198bbf069737bc32c1c9f90f847c563f5a7 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Nov 2025 21:10:45 +0000 Subject: [PATCH 17/19] Change 'repeating' to 'recurring' for tasks feature MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated terminology to use standard "recurring tasks" instead of "repeating tasks". Also updated frontmatter fields: - repeat -> recurs - repeat_until -> recurs_until "Recurring" is the more common and standard term in task management. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PLAN.md b/PLAN.md index 0e5bd1d..c227c3e 100644 --- a/PLAN.md +++ b/PLAN.md @@ -739,12 +739,12 @@ mod android { - [ ] Easy onboarding for Google Tasks users #### Advanced Task Management -- [ ] **Repeating tasks** (tasks that automatically uncomplete and reschedule) +- [ ] **Recurring tasks** (tasks that automatically uncomplete and reschedule) - When completed, task automatically returns to backlog - Due date updates by specified interval (e.g., +1 day, +1 week, +1 month) - Intervals: daily, weekly, monthly, yearly, custom (e.g., "every 3 days") - Optional: limit number of repetitions or end date - - Stored in frontmatter: `repeat: "daily"`, `repeat_until: "2026-01-01"` + - Stored in frontmatter: `recurs: "daily"`, `recurs_until: "2026-01-01"` - [ ] Task templates (save common tasks) - [ ] Bulk operations (select multiple, bulk edit) - [ ] Full-text search across all tasks From cb0f7692ab3690e59bb1306ecd7cdf408bab3550 Mon Sep 17 00:00:00 2001 From: SteelDynamite Date: Mon, 3 Nov 2025 13:21:47 -0800 Subject: [PATCH 18/19] Clarify sort order options and benefits in PLAN.md Updated sort order explanation and benefits in PLAN.md. --- PLAN.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/PLAN.md b/PLAN.md index c227c3e..42a389a 100644 --- a/PLAN.md +++ b/PLAN.md @@ -155,14 +155,7 @@ AppConfig { - `"manual"` - Tasks ordered by hand (uses `task_order` array) - `"by_due_date"` - Tasks automatically sorted by due date (tasks without due dates appear at end) -When `sort_order` is `"manual"`, the `task_order` array defines the sequence. When `sort_order` is `"by_due_date"`, tasks are sorted dynamically and `task_order` is ignored. - -**Benefits**: -- **Two sort modes**: Manual ordering or automatic by due date -- **Ordering in list metadata**: Changing manual order only touches `.listdata.json` -- **Portable lists**: Copy/move a list folder and its metadata stays with it -- **Clean structure**: No nested hidden folders, just hidden files -- **WebDAV-friendly**: Syncing a list syncs its metadata naturally +When `sort_order` is `"manual"`, the `task_order` array defines the sequence. When `sort_order` is `"by_due_date"`, tasks are grouped first and then sorted within each group by `task_order`. **App Configuration** (separate from task data): - Windows: `%APPDATA%/bevy-tasks/config.json` From 4459b339ff72c7f4aed3bdb30261178f8a705ce8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 3 Nov 2025 21:23:41 +0000 Subject: [PATCH 19/19] Add output examples to CLI usage sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enhanced CLI Usage Examples in Phase 1 and Phase 2 with realistic output examples showing: Phase 1 (Core & CLI): - Init command with success messages - Add tasks with UUID confirmation and due date display - List command showing task status, counts, and due dates - Complete/edit/delete with confirmation messages - Config and sort commands with feedback Phase 2 (WebDAV Sync): - Interactive setup with prompts and keychain confirmation - Push/pull with file upload/download progress - Automatic two-way sync with change indicators - Status command showing connection, last sync, and pending changes All examples now show: - Command prompts ($) - Realistic UUIDs - Success indicators (✓) - Progress/status information - Colored output representation (checkmarks, arrows) - Helpful feedback messages Makes it much clearer what users can expect from the CLI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- PLAN.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 85 insertions(+), 18 deletions(-) diff --git a/PLAN.md b/PLAN.md index 42a389a..38a1c4e 100644 --- a/PLAN.md +++ b/PLAN.md @@ -283,25 +283,64 @@ tokio = { workspace = true } ```bash # First run: initialize tasks folder -bevy-tasks init ~/Documents/Tasks +$ bevy-tasks init ~/Documents/Tasks +✓ Initialized tasks folder at ~/Documents/Tasks +✓ Created default list "My Tasks" # Or use a cloud-synced folder -bevy-tasks init ~/Dropbox/Tasks +$ bevy-tasks init ~/Dropbox/Tasks +✓ Initialized tasks folder at ~/Dropbox/Tasks +✓ Created default list "My 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 +# Add tasks +$ bevy-tasks add "Buy groceries" --list "Personal" +✓ Created task "Buy groceries" (550e8400-e29b-41d4-a716-446655440000) + +$ bevy-tasks add "Review PR #123" --list "Work" --due "2025-11-15" +✓ Created task "Review PR #123" (7f3a9c21-b8d2-4e5f-9a1c-3d8e7f6a2b1c) + Due: 2025-11-15 + +# List all tasks +$ bevy-tasks list +My Tasks (3 tasks) + [ ] Buy groceries + [ ] Call dentist + [✓] Pay bills + +Work (2 tasks) + [ ] Review PR #123 (due: 2025-11-15) + [ ] Team meeting prep + +# List tasks in specific list +$ bevy-tasks list --list "Work" +Work (2 tasks) + [ ] Review PR #123 (due: 2025-11-15) + [ ] Team meeting prep + +# Complete a task +$ bevy-tasks complete 550e8400-e29b-41d4-a716-446655440000 +✓ Completed task "Buy groceries" + +# Edit a task +$ bevy-tasks edit 7f3a9c21-b8d2-4e5f-9a1c-3d8e7f6a2b1c +# Opens editor with task file +✓ Updated task "Review PR #123" + +# Delete a task +$ bevy-tasks delete 550e8400-e29b-41d4-a716-446655440000 +✓ Deleted task "Buy groceries" # Change folder location later -bevy-tasks config set-folder ~/new/location +$ bevy-tasks config set-folder ~/new/location +✓ Updated tasks folder location to ~/new/location +✓ Migrated 15 tasks from ~/Documents/Tasks # Sort order -bevy-tasks sort manual --list "Work" -bevy-tasks sort by-due-date --list "Personal" +$ bevy-tasks sort manual --list "Work" +✓ Set sort order to "manual" for list "Work" + +$ bevy-tasks sort by-due-date --list "Personal" +✓ Set sort order to "by due date" for list "Personal" ``` ### Deliverables @@ -399,15 +438,43 @@ keyring = "3.0" ```bash # Setup WebDAV -bevy-tasks sync --setup -# Prompts for: URL, username, password (stored in keychain) +$ bevy-tasks sync --setup +WebDAV URL: https://nextcloud.example.com/remote.php/dav/files/username/Tasks +Username: myuser +Password: ******** +✓ WebDAV credentials saved to system keychain +✓ Connection verified -# Manual sync -bevy-tasks sync --push -bevy-tasks sync --pull +# Push local changes to WebDAV server +$ bevy-tasks sync --push +Syncing to https://nextcloud.example.com/... + Uploading My Tasks/.listdata.json + Uploading My Tasks/Buy groceries.md + Uploading Work/Review PR #123.md +✓ Pushed 3 files to WebDAV server + +# Pull changes from WebDAV server +$ bevy-tasks sync --pull +Syncing from https://nextcloud.example.com/... + Downloading Work/Team meeting notes.md + Downloading Personal/Call mom.md +✓ Pulled 2 files from WebDAV server + +# Automatic two-way sync +$ bevy-tasks sync +Syncing with https://nextcloud.example.com/... + ↑ Uploading My Tasks/New task.md + ↓ Downloading Work/Updated task.md + = No changes for 15 files +✓ Sync complete # Check sync status -bevy-tasks sync --status +$ bevy-tasks sync --status +WebDAV Server: https://nextcloud.example.com/remote.php/dav/files/username/Tasks +Status: Connected +Last sync: 2025-10-27 14:32:15 +Local changes: 2 files modified +Remote changes: 0 files modified ``` ### Deliverables