taskchampion-rb 0.2.0

data/docs/plan.md

@@ -0,0 +1,612 @@
+# TaskChampion Ruby Bindings - Completion Plan
+
+## Status Overview
+
+**Date**: 2025-01-31
+**Current State**: 🎉 **MAJOR BREAKTHROUGH ACHIEVED**
+**Core Issue**: ✅ **SOLVED** - Send trait architectural incompatibility resolved
+**Remaining Work**: Standard implementation details and polishing
+
+### What's Done ✅
+
+- **Thread Safety Solution**: ThreadBound wrapper pattern implemented and working
+- **Core Architecture**: Replica and Task types successfully use ThreadBound
+- **Magnus API Migration**: Major 0.6→0.7 compatibility issues resolved
+- **Error System**: Ruby exception hierarchy with ThreadError, StorageError, etc.
+- **Proof of Concept**: Fundamental approach validated and functional
+
+### Current Compilation Status
+
+- **Before**: 54+ errors, primary issue was `cannot be sent between threads safely`
+- **Now**: ~35 errors, all are solvable implementation details
+- **Remaining**: Method registration, parameter signatures, type conversions
+
+---
+
+## Phase 1: Complete Basic Compilation (Priority: HIGH)
+
+**Goal**: Get a clean compilation without runtime functionality
+**Timeline**: 1-2 days
+**Effort**: Medium
+
+### 1.1 Fix Magnus 0.7 Method Registration
+
+**Issue**: Methods need `&Ruby` as first parameter in Magnus 0.7
+
+**Files to Fix**:
+- `ext/taskchampion/src/tag.rs`
+- `ext/taskchampion/src/annotation.rs`
+- `ext/taskchampion/src/operation.rs`
+- `ext/taskchampion/src/operations.rs`
+- `ext/taskchampion/src/task.rs`
+- `ext/taskchampion/src/replica.rs`
+
+**Pattern**:
+```rust
+// Old (Magnus 0.6)
+fn new(param: String) -> Result<Self, Error>
+
+// New (Magnus 0.7)
+fn new(_ruby: &Ruby, param: String) -> Result<Self, Error>
+```
+
+**Method Trait Imports**:
+```rust
+// Add to imports where method! macro is used
+use magnus::method::{Function0, Function1, Function2, Function3};
+// OR research if there's a better way to import method traits
+```
+
+**Tasks**:
+- [ ] Update all method signatures to include `&Ruby` parameter
+- [ ] Import required method traits for `method!` macro
+- [ ] Fix method registration calls
+- [ ] Test compilation after each file
+
+### 1.2 Resolve Type Conversion Issues
+
+**Issue**: String ↔ Value conversions and return types
+
+**Common Patterns to Fix**:
+```rust
+// Value creation
+Value::from(()) // instead of Qnil::new() ✅ DONE
+
+// Type conversions
+Value::try_convert(v) // instead of v.try_convert() ✅ DONE
+
+// Optional returns
+option_to_ruby(value, |v| Ok(v.into())) // verify pattern works
+```
+
+**Tasks**:
+- [ ] Review all `mismatched types` errors
+- [ ] Fix String → Value conversions
+- [ ] Fix return type consistency
+- [ ] Update optional value handling
+
+### 1.3 Fix Remaining API Issues
+
+**Issue**: Magnus 0.7 API usage consistency
+
+**Tasks**:
+- [ ] Verify all `Ruby::get()` calls have proper error conversion
+- [ ] Check `const_get` usage is consistent
+- [ ] Validate `funcall` vs `ruby.funcall` patterns
+- [ ] Fix any remaining deprecated API usage
+
+**Expected Outcome**: Clean compilation with no errors
+
+---
+
+## Phase 2: Basic Functionality Testing (Priority: HIGH)
+
+**Goal**: Verify core operations work end-to-end
+**Timeline**: 1-2 days
+**Effort**: Medium
+
+### 2.1 Create Minimal Test Suite
+
+**File**: `test/test_basic_functionality.rb`
+
+```ruby
+require 'test_helper'
+
+class TestBasicFunctionality < Minitest::Test
+  def test_replica_creation
+    replica = Taskchampion::Replica.new_in_memory
+    assert_not_nil replica
+  end
+
+  def test_thread_safety_enforcement
+    replica = Taskchampion::Replica.new_in_memory
+
+    thread_error_raised = false
+    Thread.new do
+      begin
+        replica.task_uuids # Should raise ThreadError
+      rescue Taskchampion::ThreadError
+        thread_error_raised = true
+      end
+    end.join
+
+    assert thread_error_raised, "ThreadError should be raised on cross-thread access"
+  end
+
+  def test_basic_task_operations
+    replica = Taskchampion::Replica.new_in_memory
+    operations = Taskchampion::Operations.new
+
+    # Basic task creation and retrieval
+    uuid = SecureRandom.uuid
+    task = replica.create_task(uuid, operations)
+    assert_not_nil task
+
+    # Verify task can be retrieved
+    retrieved = replica.task(uuid)
+    assert_not_nil retrieved
+  end
+end
+```
+
+**Tasks**:
+- [ ] Create basic test structure
+- [ ] Test replica creation (in_memory, on_disk)
+- [ ] Verify thread safety enforcement works
+- [ ] Test basic task operations
+- [ ] Run: `bundle exec ruby test/test_basic_functionality.rb`
+
+### 2.2 Validate ThreadBound Implementation
+
+**Goal**: Ensure thread safety works as designed
+
+**Tests**:
+- [ ] **Same-thread access**: Should work normally
+- [ ] **Cross-thread access**: Should raise `Taskchampion::ThreadError`
+- [ ] **Error messages**: Should be clear and helpful
+- [ ] **Memory safety**: No segfaults or crashes
+
+**Commands**:
+```bash
+cd /home/tcase/Sites/reference/taskchampion-rb
+bundle exec ruby -e "
+  require './lib/taskchampion'
+  replica = Taskchampion::Replica.new_in_memory
+  puts 'Same thread: OK'
+
+  Thread.new do
+    begin
+      replica.task_uuids
+      puts 'ERROR: Should have raised ThreadError'
+    rescue => e
+      puts \"Cross thread raised: #{e.class} - #{e.message}\"
+    end
+  end.join
+"
+```
+
+### 2.3 Basic Ruby API Verification
+
+**Goal**: Verify Ruby-side API is usable
+
+**Tasks**:
+- [ ] Test module loading: `require 'taskchampion'`
+- [ ] Test class accessibility: `Taskchampion::Replica`, `Taskchampion::Task`
+- [ ] Test method calls don't crash
+- [ ] Verify return types are correct Ruby objects
+
+---
+
+## Phase 3: Complete API Implementation (Priority: MEDIUM)
+
+**Goal**: Implement full TaskChampion API surface
+**Timeline**: 3-5 days
+**Effort**: High
+
+### 3.1 Complete Method Registration
+
+**Goal**: Restore all method registrations that were commented out
+
+**Strategy**: Fix method registration issues systematically
+
+**Files to Complete**:
+```
+ext/taskchampion/src/tag.rs - Tag methods
+ext/taskchampion/src/annotation.rs - Annotation methods
+ext/taskchampion/src/task.rs - Task methods
+ext/taskchampion/src/operation.rs - Operation methods
+ext/taskchampion/src/operations.rs - Operations methods
+ext/taskchampion/src/replica.rs - Replica methods
+```
+
+**Method Categories**:
+- [ ] **Creation methods**: `new`, constructors
+- [ ] **Data access**: getters, setters
+- [ ] **Utility methods**: `to_s`, `inspect`, `==`, `hash`
+- [ ] **Business logic**: task operations, sync, etc.
+
+### 3.2 Implement Missing Classes
+
+**Classes needing completion**:
+- [ ] **WorkingSet**: Task working set management
+- [ ] **DependencyMap**: Task dependency tracking
+- [ ] **Status**: Task status enumeration
+- [ ] **AccessMode**: Storage access modes
+
+**Pattern for each class**:
+```rust
+#[magnus::wrap(class = "Taskchampion::ClassName", free_immediately)]
+pub struct ClassName(ThreadBound<TCClassName>);
+
+impl ClassName {
+    fn new(_ruby: &Ruby, /* params */) -> Result<Self, Error> {
+        // Implementation
+        Ok(ClassName(ThreadBound::new(tc_object)))
+    }
+
+    // Other methods...
+}
+
+pub fn init(module: &RModule) -> Result<(), Error> {
+    let class = module.define_class("ClassName", class::object())?;
+    class.define_singleton_method("new", method!(ClassName::new, /* arity */))?;
+    // Other method registrations...
+    Ok(())
+}
+```
+
+### 3.3 Ruby API Polish
+
+**Tasks**:
+- [ ] **Consistent naming**: Ensure Ruby idiomatic method names
+- [ ] **Parameter validation**: Proper error messages for invalid input
+- [ ] **Return types**: Consistent with Ruby expectations
+- [ ] **Documentation strings**: Add method documentation
+
+**Ruby Conventions**:
+```ruby
+# Good Ruby API design
+task.active?        # not task.is_active
+task.description    # not task.get_description
+task.uuid          # not task.get_uuid
+```
+
+---
+
+## Phase 4: Advanced Features & Integration (Priority: MEDIUM)
+
+**Goal**: Complete TaskChampion feature set
+**Timeline**: 2-3 days
+**Effort**: Medium
+
+### 4.1 Server Synchronization
+
+**Features**:
+- [ ] **Local sync**: `sync_to_local(server_dir, avoid_snapshots)`
+- [ ] **Remote sync**: `sync_to_remote(url:, client_id:, encryption_secret:, avoid_snapshots:)`
+- [ ] **GCP sync**: `sync_to_gcp(bucket:, credential_path:, encryption_secret:, avoid_snapshots:)`
+
+**Ruby API Design**:
+```ruby
+# Keyword arguments for complex methods
+replica.sync_to_remote(
+  url: "https://server.com",
+  client_id: uuid,
+  encryption_secret: secret,
+  avoid_snapshots: false
+)
+```
+
+### 4.2 Advanced Task Operations
+
+**Features**:
+- [ ] **Task modification**: Set properties, tags, annotations
+- [ ] **Task queries**: Find by criteria, filtering
+- [ ] **Bulk operations**: Multiple task updates
+- [ ] **Undo system**: Operation reversal
+
+### 4.3 Storage Configuration
+
+**Features**:
+- [ ] **On-disk storage**: Configurable paths, creation options
+- [ ] **In-memory storage**: For testing and temporary use
+- [ ] **Access modes**: ReadOnly, ReadWrite configurations
+- [ ] **Database migration**: Handle version upgrades
+
+---
+
+## Phase 5: Testing & Quality Assurance (Priority: HIGH)
+
+**Goal**: Comprehensive testing and stability
+**Timeline**: 2-3 days
+**Effort**: Medium
+
+### 5.1 Comprehensive Test Suite
+
+**Test Categories**:
+- [ ] **Unit tests**: Each class and method
+- [ ] **Integration tests**: End-to-end workflows
+- [ ] **Thread safety tests**: Concurrent access patterns
+- [ ] **Error handling tests**: All error conditions
+- [ ] **Memory tests**: No leaks or crashes
+
+**Test Structure**:
+```
+test/
+├── test_helper.rb
+├── unit/
+│   ├── test_replica.rb
+│   ├── test_task.rb
+│   ├── test_operations.rb
+│   └── test_thread_safety.rb
+├── integration/
+│   ├── test_task_lifecycle.rb
+│   ├── test_sync_operations.rb
+│   └── test_working_set.rb
+└── performance/
+    └── test_benchmarks.rb
+```
+
+### 5.2 Thread Safety Validation
+
+**Critical Tests**:
+```ruby
+def test_cross_thread_access_raises_error
+  replica = Taskchampion::Replica.new_in_memory
+
+  errors = []
+  threads = 10.times.map do
+    Thread.new do
+      begin
+        replica.task_uuids
+        errors << "No error raised in #{Thread.current}"
+      rescue Taskchampion::ThreadError => e
+        # Expected - this is correct behavior
+      rescue => e
+        errors << "Wrong error type: #{e.class}"
+      end
+    end
+  end
+
+  threads.each(&:join)
+  assert errors.empty?, "Thread safety issues: #{errors}"
+end
+
+def test_same_thread_access_works
+  replica = Taskchampion::Replica.new_in_memory
+
+  # Should work fine
+  uuids = replica.task_uuids
+  assert uuids.is_a?(Array)
+end
+```
+
+### 5.3 Memory Safety & Performance
+
+**Tests**:
+- [ ] **Memory leaks**: Long-running operations don't leak
+- [ ] **Crash resistance**: Invalid input doesn't crash Ruby
+- [ ] **Performance**: Reasonable performance vs pure TaskChampion
+- [ ] **Resource cleanup**: Objects are properly freed
+
+**Tools**:
+```bash
+# Memory leak detection
+valgrind --tool=memcheck ruby test/test_memory.rb
+
+# Performance benchmarking
+ruby test/performance/benchmarks.rb
+```
+
+---
+
+## Phase 6: Documentation & Polish (Priority: MEDIUM)
+
+**Goal**: Production-ready documentation and packaging
+**Timeline**: 1-2 days
+**Effort**: Low
+
+### 6.1 API Documentation
+
+**Files to create/update**:
+- [ ] **README.md**: Installation, basic usage, examples
+- [ ] **API_REFERENCE.md**: Complete API documentation
+- [ ] **THREAD_SAFETY.md**: Thread safety guidelines
+- [ ] **EXAMPLES.md**: Common usage patterns
+
+**Ruby Documentation**:
+```ruby
+# Add YARD documentation comments
+class Replica
+  # Creates a new replica with on-disk storage
+  #
+  # @param path [String] Path to task database directory
+  # @param create_if_missing [Boolean] Create database if it doesn't exist
+  # @param access_mode [Symbol] :read_write or :read_only
+  # @return [Replica] New replica instance
+  # @raise [Taskchampion::StorageError] If database cannot be accessed
+  def self.new_on_disk(path, create_if_missing: false, access_mode: :read_write)
+  end
+end
+```
+
+### 6.2 Examples and Tutorials
+
+**Example Scripts**:
+```ruby
+# examples/basic_usage.rb
+require 'taskchampion'
+
+# Create a task database
+replica = Taskchampion::Replica.new_on_disk("/tmp/tasks", create_if_missing: true)
+
+# Create some tasks
+operations = Taskchampion::Operations.new
+task1 = replica.create_task(SecureRandom.uuid, operations)
+task2 = replica.create_task(SecureRandom.uuid, operations)
+
+# Modify tasks
+task1.set_description("Learn TaskChampion Ruby bindings")
+task1.set_status(:pending)
+
+# Save changes
+replica.commit_operations(operations)
+
+# Query tasks
+all_tasks = replica.tasks
+puts "Total tasks: #{all_tasks.size}"
+
+# Sync with server (if configured)
+replica.sync_to_remote(
+  url: ENV['TASKCHAMPION_SERVER'],
+  client_id: ENV['CLIENT_ID'],
+  encryption_secret: ENV['ENCRYPTION_SECRET']
+)
+```
+
+### 6.3 Packaging & Distribution
+
+**Tasks**:
+- [ ] **Gemspec polish**: Proper dependencies, descriptions, metadata
+- [ ] **Version management**: Semantic versioning aligned with TaskChampion
+- [ ] **Build automation**: CI/CD for multiple Ruby versions and platforms
+- [ ] **Precompiled gems**: Binary gems for major platforms
+
+---
+
+## Phase 7: Production Readiness (Priority: LOW)
+
+**Goal**: Production deployment preparation
+**Timeline**: 1-2 days
+**Effort**: Low
+
+### 7.1 Error Handling & Logging
+
+**Features**:
+- [ ] **Comprehensive error coverage**: All TaskChampion errors mapped to Ruby
+- [ ] **Logging integration**: Optional logging support
+- [ ] **Debug modes**: Detailed error information in development
+- [ ] **Graceful degradation**: Handle edge cases smoothly
+
+### 7.2 Platform Support
+
+**Targets**:
+- [ ] **Ruby versions**: 3.0, 3.1, 3.2, 3.3, 3.4
+- [ ] **Platforms**: Linux (x86_64, ARM64), macOS (Intel, Apple Silicon), Windows
+- [ ] **Precompiled gems**: Reduce compilation requirements for users
+
+### 7.3 Community & Maintenance
+
+**Tasks**:
+- [ ] **Contributing guidelines**: How to contribute to the project
+- [ ] **Issue templates**: Bug reports, feature requests
+- [ ] **Release process**: Automated releases with changelogs
+- [ ] **Community docs**: Integration with broader TaskChampion ecosystem
+
+---
+
+## Risk Assessment & Mitigation
+
+### Low Risk ✅
+- **Thread safety implementation**: Core pattern is proven and working
+- **Basic API surface**: Standard Ruby/C extension patterns
+- **Documentation**: Straightforward technical writing
+
+### Medium Risk ⚠️
+- **Magnus 0.7 method registration**: May require more research
+- **Complex API methods**: Server sync, advanced operations
+- **Performance optimization**: May need tuning
+
+### High Risk ⚡
+- **Cross-platform compilation**: Platform-specific issues possible
+- **Memory management edge cases**: Complex object lifecycles
+- **TaskChampion API changes**: Future compatibility
+
+### Mitigation Strategies
+1. **Incremental approach**: Test each phase before proceeding
+2. **Community engagement**: Ask Magnus maintainers for guidance
+3. **Fallback plans**: Simplify features if complexity is too high
+4. **Version pinning**: Pin TaskChampion version to avoid surprises
+
+---
+
+## Success Metrics
+
+### Phase Completion Criteria
+
+**Phase 1 Success**:
+- ✅ Clean compilation (0 errors)
+- ✅ Basic gem loading works
+- ✅ No crashes on simple operations
+
+**Phase 2 Success**:
+- ✅ Thread safety enforcement works
+- ✅ Basic task operations complete
+- ✅ Simple test suite passes
+
+**Phase 3 Success**:
+- ✅ Full API surface available
+- ✅ All major classes implemented
+- ✅ Ruby-idiomatic interface
+
+**Final Success**:
+- ✅ Comprehensive test suite passes
+- ✅ Production-ready documentation
+- ✅ Community can use the gem successfully
+
+### Quality Gates
+
+- **Code quality**: No compiler warnings, clean lints
+- **Memory safety**: No crashes, leaks, or undefined behavior
+- **API consistency**: Ruby conventions followed throughout
+- **Performance**: Reasonable overhead vs native TaskChampion
+- **Documentation**: Complete and accurate API reference
+
+---
+
+## Getting Started
+
+### Immediate Next Steps (Today)
+
+1. **Start with Phase 1.1**: Fix method registration issues
+   ```bash
+   cd /home/tcase/Sites/reference/taskchampion-rb
+   bundle exec rake compile 2>&1 | grep "call_handle_error" | head -5
+   ```
+
+2. **Focus on one file at a time**: Start with `tag.rs` (smallest scope)
+
+3. **Research Magnus 0.7 patterns**: Look for working examples
+
+4. **Test incrementally**: Compile after each fix
+
+### Daily Progress Tracking
+
+Create daily progress files:
+- `progress/2025-01-31.md` - Document what was accomplished
+- Track compilation error count reduction
+- Note any blockers or discoveries
+- Plan next day's priorities
+
+### Resource Links
+
+- **Magnus Documentation**: https://docs.rs/magnus/0.7.1/magnus/
+- **TaskChampion Rust API**: https://docs.rs/taskchampion/2.0.2/taskchampion/
+- **Ruby C Extensions Guide**: https://guides.rubygems.org/gems-with-extensions/
+- **Thread Safety Patterns**: Ruby concurrency best practices
+
+---
+
+## Conclusion
+
+The hardest part is **DONE**. The architectural breakthrough has been achieved, and what remains is systematic implementation work.
+
+**Key Insight**: We've proven that Magnus CAN handle non-Send types, opening up possibilities for many other Rust libraries that were previously thought incompatible with Ruby bindings.
+
+**Path Forward**: Follow this plan systematically, test incrementally, and don't hesitate to simplify features if they become too complex. The core functionality is working, and everything else is additive.
+
+🎯 **Focus**: Get Phase 1 completed first - clean compilation is the foundation for everything else.
+
+**Estimated Total Time**: 2-3 weeks for full completion
+**Minimum Viable Product**: 1 week (through Phase 2)
+**Production Ready**: 2-3 weeks (through Phase 6)