taskchampion-rb 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 494521791e308dacc686f45ef7ff87937a0038e46729092a4e145952971a5f56
-  data.tar.gz: ac3a7b7367b2d8565ac902981fb4c7a9ee45b7d0c825868b15591211debc733b
+  metadata.gz: 9c5bf1065611d68b14549f0c6930e630f6e79483699d2ad05d2e1211da8192ac
+  data.tar.gz: f9cd13e961c3b814c4eb8474e22e585803e24f426f92e49dbb24c716640c52ee
 SHA512:
-  metadata.gz: 3d5c1e59e10ac46d98a8fc30d666dac904fcf2d14742c12713a16050a7a67d87c21e1a42ebaf7d25762541d0335c3c36ab2cf6a93bd3ed778046cd1a739840f4
-  data.tar.gz: 8f69921b628b5b1803a940584b05dd46abc854e50d9a3555646a141298a6c2a55008b2c8ca60b508fd53566bc6d0bd28a69f8caf76021e37a56e9fbf69bd362c
+  metadata.gz: 2724376c451663195d870dedf33dae60e50058909bb35ab89dad2c93b80e30b0aeacb19f0d412c41d2805a5c5fd9c447da5224808d060ddd241c06cabbfa4994
+  data.tar.gz: d6f75a71a7e4a040fe471c741c0f1842d09f36101009842896f8c74c9335aea8e5d72cc2fb707cb2088590835b508d632e2adc1c0103e136fc79d8b58b35be93

data/README.md

@@ -8,6 +8,7 @@ This gem supports Ruby 3.2 and later. We follow Ruby's end-of-life (EOL) schedul
 
 - **Ruby 3.2**: Supported (EOL: March 2026)
 - **Ruby 3.3**: Supported (Current stable)
+- **Ruby 3.4**: Supported
 - **Ruby 3.0-3.1**: Not supported (reached EOL)
 
 ## Installation

data/docs/date_conversion_analysis.md

@@ -0,0 +1,113 @@
+# Date Format Conversion in `task.set_due`
+
+## Overview
+
+When `task.set_due` is invoked in the TaskChampion Ruby gem, there **is** a format conversion from various Ruby date/time formats to a Unix timestamp for storage.
+
+## Conversion Flow
+
+The conversion follows this path: **Ruby date/time → UTC DateTime → Unix timestamp (stored as string)**
+
+### 1. Ruby Input Processing
+**Location**: `ext/taskchampion/src/task.rs:258-264`
+
+The `set_due` method accepts a Ruby `Value` which can be:
+- `nil` (to clear the due date)
+- A Ruby `Time` object
+- A Ruby `DateTime` object
+- A String in ISO 8601 format (e.g., "2023-01-01T12:00:00Z")
+- A String in the format "%Y-%m-%d %H:%M:%S %z"
+
+```rust
+fn set_due(&self, due: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+    let mut task = self.0.get_mut()?;
+    let due_datetime = ruby_to_option(due, ruby_to_datetime)?;
+    operations.with_inner_mut(|ops| {
+        task.set_due(due_datetime, ops)
+    })?;
+    Ok(())
+}
+```
+
+### 2. Conversion to Rust DateTime
+**Location**: `ext/taskchampion/src/util.rs:33-77`
+
+The `ruby_to_datetime` function converts the Ruby value to a Rust `DateTime<Utc>`:
+
+- **For `Time` objects**: Uses `strftime("%Y-%m-%dT%H:%M:%S%z")` to get ISO format, then parses it
+- **For `DateTime` objects**: Calls the `iso8601()` method, then parses the result
+- **For Strings**: Attempts to parse as RFC3339 first, then falls back to "%Y-%m-%d %H:%M:%S %z" format
+- **All dates are converted to UTC timezone**
+
+```rust
+pub fn ruby_to_datetime(value: Value) -> Result<DateTime<Utc>, Error> {
+    // String parsing
+    if let Ok(s) = RString::try_convert(value) {
+        let s = unsafe { s.as_str()? };
+        DateTime::parse_from_rfc3339(s)
+            .map(|dt| dt.with_timezone(&Utc))
+            .or_else(|_| DateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S %z")
+                .map(|dt| dt.with_timezone(&Utc)))
+            // ... error handling
+    } else {
+        // Ruby Time/DateTime object handling
+        let class_name = unsafe { value.class().name() };
+        let iso_string = if class_name == "Time" {
+            value.funcall::<_, (&str,), String>("strftime", ("%Y-%m-%dT%H:%M:%S%z",))?
+        } else {
+            value.funcall::<_, (), String>("iso8601", ())?
+        };
+        // Parse the ISO string...
+    }
+}
+```
+
+### 3. Storage as Unix Timestamp
+**Location**: `/home/tcase/Sites/reference/taskchampion/src/task/task.rs`
+
+The underlying TaskChampion library stores the date as a Unix timestamp:
+
+```rust
+pub fn set_due(&mut self, due: Option<Timestamp>, ops: &mut Operations) -> Result<()> {
+    self.set_timestamp(Prop::Due.as_ref(), due, ops)
+}
+
+pub fn set_timestamp(
+    &mut self,
+    property: &str,
+    value: Option<Timestamp>,
+    ops: &mut Operations,
+) -> Result<()> {
+    self.set_value(property, value.map(|v| v.timestamp().to_string()), ops)
+}
+```
+
+Where `Timestamp` is defined as:
+```rust
+pub(crate) type Timestamp = DateTime<Utc>;
+```
+
+The `.timestamp()` method converts the `DateTime<Utc>` to Unix timestamp (seconds since epoch), which is then converted to a string for storage (e.g., "1704067200").
+
+### 4. Retrieval Process
+**Location**: `ext/taskchampion/src/task.rs`
+
+When retrieving the due date, it's converted back from Unix timestamp to a Ruby DateTime object:
+
+```rust
+fn due(&self) -> Result<Value, Error> {
+    let task = self.0.get()?;
+    option_to_ruby(task.get_due(), datetime_to_ruby)
+}
+```
+
+## Summary
+
+The `task.set_due` method performs comprehensive date format conversion:
+
+1. **Input**: Accepts various Ruby date/time formats and strings
+2. **Normalization**: Converts all inputs to UTC `DateTime<Utc>`
+3. **Storage**: Stores as Unix timestamp string in the underlying TaskChampion database
+4. **Retrieval**: Converts back to Ruby DateTime objects when accessed
+
+This ensures consistent date handling across different input formats while maintaining precision and timezone normalization.

data/docs/errors.md

@@ -0,0 +1,151 @@
+# TaskChampion Ruby Error Reference
+
+## Error Hierarchy
+
+All TaskChampion errors inherit from `Taskchampion::Error`, which inherits from Ruby's `StandardError`.
+
+```
+StandardError
+└── Taskchampion::Error
+    ├── Taskchampion::ThreadError
+    ├── Taskchampion::StorageError
+    ├── Taskchampion::ValidationError
+    ├── Taskchampion::ConfigError
+    └── Taskchampion::SyncError
+```
+
+## Error Types
+
+### Taskchampion::ValidationError
+
+Raised when data validation fails, including:
+- Invalid UUID format
+- Invalid datetime format
+- Parse errors
+- Format validation failures
+
+**Example:**
+```ruby
+# Invalid UUID format
+replica.create_task("bad-uuid", operations)
+# => Taskchampion::ValidationError: Invalid UUID format: 'bad-uuid'. Expected format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+### Taskchampion::ThreadError
+
+Raised when an object is accessed from a different thread than the one that created it. TaskChampion enforces thread safety by requiring objects to be accessed only from their creation thread.
+
+**Example:**
+```ruby
+replica = Taskchampion::Replica.new_in_memory
+Thread.new { replica.all_tasks }.join
+# => Taskchampion::ThreadError: Object accessed from wrong thread
+```
+
+### Taskchampion::StorageError
+
+Raised for database and storage-related issues:
+- File not found
+- Permission denied
+- Database corruption
+- Storage access failures
+
+**Example:**
+```ruby
+Taskchampion::Replica.new_on_disk("/invalid/path", false)
+# => Taskchampion::StorageError: Storage error: No such file or directory
+```
+
+### Taskchampion::ConfigError
+
+Raised when configuration is invalid or missing required parameters:
+- Invalid configuration values
+- Missing required configuration
+
+**Example:**
+```ruby
+# Missing required sync configuration
+replica.sync_to_remote(url: "https://example.com")
+# => Taskchampion::ConfigError: Configuration error: missing client_id
+```
+
+### Taskchampion::SyncError
+
+Raised during synchronization operations:
+- Network failures
+- Server connection issues
+- Remote sync problems
+- Authentication failures
+
+**Example:**
+```ruby
+replica.sync_to_remote(
+  url: "https://invalid.server",
+  client_id: "...",
+  encryption_secret: "..."
+)
+# => Taskchampion::SyncError: Synchronization error: network timeout
+```
+
+### Taskchampion::Error
+
+Generic error class for TaskChampion errors that don't fall into specific categories. This is the base class for all TaskChampion-specific errors.
+
+## Common Error Scenarios
+
+### Creating Tasks
+
+```ruby
+begin
+  task = replica.create_task(uuid, operations)
+rescue Taskchampion::ValidationError => e
+  # Handle invalid UUID format
+  puts "Invalid UUID: #{e.message}"
+rescue Taskchampion::StorageError => e
+  # Handle storage issues
+  puts "Storage problem: #{e.message}"
+rescue Taskchampion::ThreadError => e
+  # Handle thread safety violation
+  puts "Thread error: #{e.message}"
+end
+```
+
+### Synchronization
+
+```ruby
+begin
+  replica.sync_to_remote(
+    url: server_url,
+    client_id: client_id,
+    encryption_secret: secret
+  )
+rescue Taskchampion::SyncError => e
+  # Handle sync failures
+  puts "Sync failed: #{e.message}"
+rescue Taskchampion::ConfigError => e
+  # Handle configuration issues
+  puts "Config error: #{e.message}"
+end
+```
+
+### File Operations
+
+```ruby
+begin
+  replica = Taskchampion::Replica.new_on_disk(path, false, :read_write)
+rescue Taskchampion::StorageError => e
+  # Handle file access issues
+  puts "Cannot access database: #{e.message}"
+end
+```
+
+## Error Message Patterns
+
+The error mapping system examines error message content to determine the appropriate exception type:
+
+- Messages containing "storage", "database", "No such file", or "Permission denied" → `StorageError`
+- Messages containing "sync", "server", "network", or "remote" → `SyncError`
+- Messages containing "config" or "invalid config" → `ConfigError`
+- Messages containing "invalid", "parse", "format", or "validation" → `ValidationError`
+- Thread access violations → `ThreadError`
+- All other TaskChampion errors → `Error` (base class)

data/examples/pending_tasks.rb

@@ -53,4 +53,4 @@ pending.each_with_index do |task, index|
 end
 
 puts "\n" + "=" * 50
-puts "For comparison, all_tasks returns #{replica.all_tasks.size} tasks total"
+puts "For comparison, all_tasks returns #{replica.all_tasks.size} tasks total"

data/examples/undo_demo.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/taskchampion"
+
+# Create a replica for this demo
+replica = Taskchampion::Replica.new_in_memory
+
+puts "=== TaskChampion Undo/History Demo ==="
+
+# Create first task with undo point
+puts "\n1. Creating first task..."
+ops1 = Taskchampion::Operations.new
+ops1.push(Taskchampion::Operation.undo_point)
+task1 = replica.create_task("550e8400-e29b-41d4-a716-446655440000", ops1)
+task1.set_description("First task", ops1)
+replica.commit_operations(ops1)
+
+# Create second task with undo point
+puts "2. Creating second task..."
+ops2 = Taskchampion::Operations.new
+ops2.push(Taskchampion::Operation.undo_point)
+task2 = replica.create_task("550e8400-e29b-41d4-a716-446655440001", ops2)
+task2.set_description("Second task", ops2)
+task2.set_value("project", "home", ops2)
+replica.commit_operations(ops2)
+
+# Update task2's description to show old_value -> new_value
+puts "\n3. Updating second task's description..."
+ops3 = Taskchampion::Operations.new
+task2.set_description("Updated second task", ops3)
+replica.commit_operations(ops3)
+
+# Show current tasks
+puts "\n4. Current tasks:"
+replica.all_tasks.each do |uuid, task|
+  puts "  - #{task.description} (#{uuid})"
+end
+
+# Show task history for task2
+puts "\n5. History for second task:"
+task2_ops = replica.task_operations(task2.uuid)
+puts "  Operations count: #{task2_ops.length}"
+task2_ops.to_a.each_with_index do |op, i|
+  puts "  #{i + 1}. #{op.operation_type}"
+  if op.operation_type == :update
+    old_val = op.old_value.nil? ? "(none)" : op.old_value
+    new_val = op.value.nil? ? "(none)" : op.value
+    puts "    Details: #{op.property} changed from #{old_val} to #{new_val} at #{op.timestamp}"
+  end
+end
+
+# Check undo points available
+puts "\n6. Undo points available: #{replica.num_undo_points}"
+
+# Show what would be undone
+puts "\n7. Operations that would be undone:"
+undo_ops = replica.undo_operations
+puts "  Operations to undo: #{undo_ops.length}"
+undo_ops.to_a.each_with_index do |op, i|
+  puts "  #{i + 1}. #{op.operation_type}"
+end
+
+# Perform undo
+puts "\n8. Performing undo..."
+result = replica.undo!
+puts "  Undo successful: #{result}"
+
+# Show tasks after undo
+puts "\n9. Tasks after first undo:"
+tasks = replica.all_tasks
+if tasks.empty?
+  puts "  No tasks"
+else
+  tasks.each do |uuid, task|
+    puts "  - #{task.description} (#{uuid})"
+  end
+end
+
+# Show remaining undo points
+puts "\n10. Remaining undo points: #{replica.num_undo_points}"
+
+# Perform another undo
+if replica.num_undo_points > 0
+  puts "\n11. Performing second undo..."
+  result = replica.undo!
+  puts "   Undo successful: #{result}"
+
+  puts "\n12. Tasks after second undo:"
+  tasks = replica.all_tasks
+  if tasks.empty?
+    puts "   No tasks remaining"
+  else
+    tasks.each do |uuid, task|
+      puts "   - #{task.description} (#{uuid})"
+    end
+  end
+
+  puts "\n13. Final undo points: #{replica.num_undo_points}"
+else
+  puts "\n11. No more undo points available"
+end
+
+puts "\n=== Demo Complete ==="

data/ext/taskchampion/src/operations.rs

@@ -137,6 +137,15 @@ impl Operations {
         }
         Ok(())
     }
+
+    // Internal method for creating Operations from TaskChampion operations
+    pub(crate) fn from_tc_operations(tc_ops: Vec<taskchampion::Operation>) -> Self {
+        let mut operations = TCOperations::new();
+        for op in tc_ops {
+            operations.push(op);
+        }
+        Operations(ThreadBound::new(RefCell::new(operations)))
+    }
 }
 
 // Note: AsRef and AsMut cannot be implemented with RefCell

data/ext/taskchampion/src/replica.rs

@@ -93,6 +93,20 @@ impl Replica {
         Ok(hash)
     }
 
+    fn pending_tasks(&self) -> Result<RArray, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        let tc_tasks = tc_replica.pending_tasks().map_err(into_error)?;
+
+        let array = RArray::new();
+        for tc_task in tc_tasks {
+            let ruby_task = crate::task::Task::from_tc_task(tc_task);
+            array.push(ruby_task)?;
+        }
+
+        Ok(array)
+    }
+
     fn task_data(&self, uuid: String) -> Result<Value, Error> {
         let mut tc_replica = self.0.get_mut()?;
 
@@ -261,19 +275,37 @@ impl Replica {
         Ok(tc_replica.num_undo_points().map_err(into_error)?)
     }
 
-    fn pending_tasks(&self) -> Result<RArray, Error> {
+    fn get_task_operations(&self, uuid: String) -> Result<Value, Error> {
         let mut tc_replica = self.0.get_mut()?;
+        let tc_uuid = uuid2tc(&uuid)?;
 
-        let tc_tasks = tc_replica.pending_tasks().map_err(into_error)?;
+        let tc_operations = tc_replica.get_task_operations(tc_uuid).map_err(into_error)?;
+        let operations = Operations::from_tc_operations(tc_operations);
 
-        let array = RArray::new();
-        for tc_task in tc_tasks {
-            let ruby_task = crate::task::Task::from_tc_task(tc_task);
-            array.push(ruby_task)?;
-        }
+        Ok(operations.into_value())
+    }
 
-        Ok(array)
+    fn get_undo_operations(&self) -> Result<Value, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        let tc_operations = tc_replica.get_undo_operations().map_err(into_error)?;
+        let operations = Operations::from_tc_operations(tc_operations);
+
+        Ok(operations.into_value())
     }
+
+    fn commit_reversed_operations(&self, operations: &Operations) -> Result<bool, Error> {
+        let mut tc_replica = self.0.get_mut()?;
+
+        // Convert Operations to TaskChampion Operations
+        let tc_operations = operations.clone_inner()?;
+
+        // Commit the reversed operations
+        let success = tc_replica.commit_reversed_operations(tc_operations).map_err(into_error)?;
+
+        Ok(success)
+    }
+
 }
 
 pub fn init(module: &RModule) -> Result<(), Error> {
@@ -299,6 +331,9 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("expire_tasks", method!(Replica::expire_tasks, 0))?;
     class.define_method("num_local_operations", method!(Replica::num_local_operations, 0))?;
     class.define_method("num_undo_points", method!(Replica::num_undo_points, 0))?;
+    class.define_method("get_task_operations", method!(Replica::get_task_operations, 1))?;
+    class.define_method("get_undo_operations", method!(Replica::get_undo_operations, 0))?;
+    class.define_method("commit_reversed_operations", method!(Replica::commit_reversed_operations, 1))?;
     class.define_method("pending_tasks", method!(Replica::pending_tasks, 0))?;
 
     Ok(())

data/ext/taskchampion/src/task.rs

@@ -264,6 +264,15 @@ impl Task {
         Ok(())
     }
 
+    fn set_entry(&self, entry: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+        let entry_datetime = ruby_to_option(entry, ruby_to_datetime)?;
+        operations.with_inner_mut(|ops| {
+            task.set_entry(entry_datetime, ops)
+        })?;
+        Ok(())
+    }
+
     fn set_value(&self, property: String, value: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
         if property.trim().is_empty() {
             return Err(Error::new(
@@ -284,6 +293,53 @@ impl Task {
         Ok(())
     }
 
+    fn set_timestamp(&self, property: String, timestamp: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if property.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Property name cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        let timestamp_datetime = ruby_to_option(timestamp, ruby_to_datetime)?;
+
+        // Convert timestamp to Unix timestamp string, or None for clearing
+        let timestamp_str = timestamp_datetime.map(|dt| dt.timestamp().to_string());
+
+        operations.with_inner_mut(|ops| {
+            task.set_value(&property, timestamp_str, ops)
+        })?;
+        Ok(())
+    }
+
+    fn get_timestamp(&self, property: String) -> Result<Value, Error> {
+        if property.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Property name cannot be empty or whitespace-only"
+            ));
+        }
+
+        let task = self.0.get()?;
+
+        // Get the value as string and attempt to parse as Unix timestamp
+        match task.get_value(&property) {
+            Some(timestamp_str) => {
+                // Parse the string as Unix timestamp (seconds since epoch)
+                if let Ok(timestamp_secs) = timestamp_str.parse::<i64>() {
+                    use chrono::{DateTime, Utc};
+                    if let Some(dt) = DateTime::from_timestamp(timestamp_secs, 0) {
+                        return datetime_to_ruby(dt);
+                    }
+                }
+                // If parsing fails, return nil
+                Ok(().into_value())
+            },
+            None => Ok(().into_value()) // Return nil if property doesn't exist
+        }
+    }
+
     fn set_uda(&self, namespace: String, key: String, value: String, operations: &crate::operations::Operations) -> Result<(), Error> {
         if namespace.trim().is_empty() {
             return Err(Error::new(
@@ -389,7 +445,10 @@ pub fn init(module: &RModule) -> Result<(), Error> {
     class.define_method("remove_tag", method!(Task::remove_tag, 2))?;
     class.define_method("add_annotation", method!(Task::add_annotation, 2))?;
     class.define_method("set_due", method!(Task::set_due, 2))?;
+    class.define_method("set_entry", method!(Task::set_entry, 2))?;
     class.define_method("set_value", method!(Task::set_value, 3))?;
+    class.define_method("set_timestamp", method!(Task::set_timestamp, 3))?;
+    class.define_method("get_timestamp", method!(Task::get_timestamp, 1))?;
     class.define_method("set_uda", method!(Task::set_uda, 4))?;
     class.define_method("delete_uda", method!(Task::delete_uda, 3))?;
     class.define_method("done", method!(Task::done, 1))?;

data/lib/taskchampion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taskchampion
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

data/lib/taskchampion.rb

@@ -37,5 +37,24 @@ module Taskchampion
       ws.replica = self
       ws
     end
+
+    # Ruby-style convenience methods for undo functionality
+    def task_operations(uuid)
+      get_task_operations(uuid)
+    end
+
+    def undo_operations
+      get_undo_operations
+    end
+
+    def commit_undo!(operations)
+      commit_reversed_operations(operations)
+    end
+
+    def undo!
+      ops = undo_operations
+      return false if ops.empty?
+      commit_undo!(ops)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskchampion-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Tim Case
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
+date: 2025-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -44,13 +44,16 @@ files:
 - docs/API_REFERENCE.md
 - docs/THREAD_SAFETY.md
 - docs/breakthrough.md
+- docs/date_conversion_analysis.md
 - docs/description.md
+- docs/errors.md
 - docs/phase_3_plan.md
 - docs/plan.md
 - example.md
 - examples/basic_usage.rb
 - examples/pending_tasks.rb
 - examples/sync_workflow.rb
+- examples/undo_demo.rb
 - ext/taskchampion/Cargo.toml
 - ext/taskchampion/extconf.rb
 - ext/taskchampion/src/access_mode.rs