taskchampion-rb 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 494521791e308dacc686f45ef7ff87937a0038e46729092a4e145952971a5f56
-  data.tar.gz: ac3a7b7367b2d8565ac902981fb4c7a9ee45b7d0c825868b15591211debc733b
+  metadata.gz: cafd2930e70aef0ac31c03c98e3d806cd1fba49408ce69b4bcb5d41074465c3f
+  data.tar.gz: 23b8948a759f8cc7b28e2cb68d65d40750943bd05bf127a87f5e25bf80116900
 SHA512:
-  metadata.gz: 3d5c1e59e10ac46d98a8fc30d666dac904fcf2d14742c12713a16050a7a67d87c21e1a42ebaf7d25762541d0335c3c36ab2cf6a93bd3ed778046cd1a739840f4
-  data.tar.gz: 8f69921b628b5b1803a940584b05dd46abc854e50d9a3555646a141298a6c2a55008b2c8ca60b508fd53566bc6d0bd28a69f8caf76021e37a56e9fbf69bd362c
+  metadata.gz: 2ff558c7674c2ff686e08ec9e220baa966edf438353e42832a566771cbcb2348c329d34fa27937b7bc9b71c0fdd7721f6e3086a675a5baa4e54f2e4e102600a5
+  data.tar.gz: 34dfcc7ea08bc2f90b846d3a19b1526731a0142d1cc6d09a867923bd6620be3abc13602eab12f8022c85dfc10b3f97502c62419808db3b942808489efbd51488

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/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(
@@ -389,6 +398,7 @@ 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_uda", method!(Task::set_uda, 4))?;
     class.define_method("delete_uda", method!(Task::delete_uda, 3))?;

data/lib/taskchampion/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: taskchampion-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Tim Case
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
+date: 2025-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -45,6 +45,7 @@ files:
 - docs/THREAD_SAFETY.md
 - docs/breakthrough.md
 - docs/description.md
+- docs/errors.md
 - docs/phase_3_plan.md
 - docs/plan.md
 - example.md