taskchampion-rb 0.2.0

data/ext/taskchampion/src/task.rs

@@ -0,0 +1,388 @@
+use magnus::{
+    class, method, prelude::*, Error, IntoValue, RArray, RModule, Symbol, TryConvert, Value,
+};
+use taskchampion::Task as TCTask;
+
+use crate::annotation::Annotation;
+use crate::status::Status;
+use crate::tag::Tag;
+use crate::thread_check::ThreadBound;
+use crate::util::{datetime_to_ruby, into_error, option_to_ruby, ruby_to_datetime, ruby_to_option, vec_to_ruby};
+
+#[magnus::wrap(class = "Taskchampion::Task", free_immediately)]
+pub struct Task(ThreadBound<TCTask>);
+
+impl Task {
+    pub fn from_tc_task(tc_task: TCTask) -> Self {
+        Task(ThreadBound::new(tc_task))
+    }
+
+    fn inspect(&self) -> Result<String, Error> {
+        let task = self.0.get()?;
+        Ok(format!("#<Taskchampion::Task: {}>", task.get_uuid()))
+    }
+
+    fn uuid(&self) -> Result<String, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_uuid().to_string())
+    }
+
+    fn status(&self) -> Result<Symbol, Error> {
+        let task = self.0.get()?;
+        Ok(Status::from(task.get_status()).to_symbol())
+    }
+
+    fn description(&self) -> Result<String, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_description().to_string())
+    }
+
+    fn entry(&self) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        option_to_ruby(task.get_entry(), datetime_to_ruby)
+    }
+
+    fn priority(&self) -> Result<String, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_priority().to_string())
+    }
+
+    fn wait(&self) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        option_to_ruby(task.get_wait(), datetime_to_ruby)
+    }
+
+    fn modified(&self) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        option_to_ruby(task.get_modified(), datetime_to_ruby)
+    }
+
+    fn due(&self) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        option_to_ruby(task.get_due(), datetime_to_ruby)
+    }
+
+    fn dependencies(&self) -> Result<RArray, Error> {
+        let task = self.0.get()?;
+        let deps: Vec<String> = task.get_dependencies().map(|uuid| uuid.to_string()).collect();
+        vec_to_ruby(deps, |s| Ok(s.into_value()))
+    }
+
+    // Boolean methods with ? suffix
+    fn waiting(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.is_waiting())
+    }
+
+    fn active(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.is_active())
+    }
+
+    fn blocked(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.is_blocked())
+    }
+
+    fn blocking(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.is_blocking())
+    }
+
+    fn completed(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_status() == taskchampion::Status::Completed)
+    }
+
+    fn deleted(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_status() == taskchampion::Status::Deleted)
+    }
+
+    fn pending(&self) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.get_status() == taskchampion::Status::Pending)
+    }
+
+    // Tag methods
+    fn has_tag(&self, tag: &Tag) -> Result<bool, Error> {
+        let task = self.0.get()?;
+        Ok(task.has_tag(tag.as_ref()))
+    }
+
+    fn tags(&self) -> Result<RArray, Error> {
+        let task = self.0.get()?;
+        let tags: Vec<Tag> = task.get_tags().map(Tag::from).collect();
+        vec_to_ruby(tags, |tag| {
+            Ok(tag.into_value()) // Convert to Value using IntoValue trait
+        })
+    }
+
+    fn annotations(&self) -> Result<RArray, Error> {
+        let task = self.0.get()?;
+        let annotations: Vec<Annotation> = task.get_annotations().map(Annotation::from).collect();
+        vec_to_ruby(annotations, |ann| {
+            Ok(ann.into_value()) // Convert to Value using IntoValue trait
+        })
+    }
+
+    // Value access
+    fn get_value(&self, property: String) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        match task.get_value(property) {
+            Some(value) => Ok(value.into_value()),
+            None => Ok(().into_value()), // () converts to nil in Magnus
+        }
+    }
+
+    fn get_uda(&self, namespace: String, key: String) -> Result<Value, Error> {
+        let task = self.0.get()?;
+        match task.get_uda(&namespace, &key) {
+            Some(value) => Ok(value.into_value()),
+            None => Ok(().into_value()), // () converts to nil in Magnus
+        }
+    }
+
+    fn udas(&self) -> Result<RArray, Error> {
+        let task = self.0.get()?;
+        let udas: Vec<((String, String), String)> = task.get_udas()
+            .map(|((ns, key), value)| ((ns.to_string(), key.to_string()), value.to_string()))
+            .collect();
+
+        vec_to_ruby(udas, |(key_tuple, value)| {
+            let array = RArray::new();
+            let key_array = RArray::new();
+            key_array.push(key_tuple.0)?;
+            key_array.push(key_tuple.1)?;
+            array.push(key_array)?;
+            array.push(value)?;
+            Ok(array.into_value())
+        })
+    }
+
+    // Mutation methods that require Operations parameter
+    fn set_description(&self, description: String, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if description.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Description cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.set_description(description.clone(), ops)
+        })?;
+        Ok(())
+    }
+
+    fn set_status(&self, status: Value, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+
+        // Handle both Status objects and symbols
+        let status = if let Ok(status_obj) = <&Status>::try_convert(status) {
+            *status_obj // Copy the Status object
+        } else if let Ok(symbol) = Symbol::try_convert(status) {
+            Status::from_symbol(symbol)?
+        } else {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Status must be a Taskchampion::Status object or a symbol (:pending, :completed, :deleted, etc.)"
+            ));
+        };
+
+        operations.with_inner_mut(|ops| {
+            task.set_status(status.into(), ops)
+        })?;
+        Ok(())
+    }
+
+    fn set_priority(&self, priority: String, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if priority.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Priority cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.set_priority(priority.clone(), ops)
+        })?;
+        Ok(())
+    }
+
+    fn add_tag(&self, tag: &Tag, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.add_tag(tag.as_ref(), ops)
+        })?;
+        Ok(())
+    }
+
+    fn remove_tag(&self, tag: &Tag, operations: &crate::operations::Operations) -> Result<(), Error> {
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.remove_tag(tag.as_ref(), ops)
+        })?;
+        Ok(())
+    }
+
+    fn add_annotation(&self, description: String, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if description.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "Annotation description cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        use chrono::Utc;
+        use std::sync::atomic::{AtomicU64, Ordering};
+
+        // Use an atomic counter to ensure unique second-level timestamps
+        // TaskChampion appears to truncate sub-second precision in property keys
+        static ANNOTATION_COUNTER: AtomicU64 = AtomicU64::new(0);
+        let counter = ANNOTATION_COUNTER.fetch_add(1, Ordering::SeqCst);
+
+        // Get current time and add second offset to ensure uniqueness at TaskChampion's precision level
+        let base_time = Utc::now();
+        let now = base_time + chrono::Duration::seconds(counter as i64);
+        let annotation = taskchampion::Annotation { entry: now, description: description.clone() };
+        operations.with_inner_mut(|ops| {
+            task.add_annotation(annotation, ops)
+        })?;
+        Ok(())
+    }
+
+    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(())
+    }
+
+    fn set_value(&self, property: String, value: 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 value_str = if value.is_nil() {
+            None
+        } else {
+            Some(value.to_string())
+        };
+        operations.with_inner_mut(|ops| {
+            task.set_value(&property, value_str, ops)
+        })?;
+        Ok(())
+    }
+
+    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(
+                crate::error::validation_error(),
+                "UDA namespace cannot be empty or whitespace-only"
+            ));
+        }
+        if key.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "UDA key cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.set_uda(&namespace, &key, &value, ops)
+        })?;
+        Ok(())
+    }
+
+    fn delete_uda(&self, namespace: String, key: String, operations: &crate::operations::Operations) -> Result<(), Error> {
+        if namespace.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "UDA namespace cannot be empty or whitespace-only"
+            ));
+        }
+        if key.trim().is_empty() {
+            return Err(Error::new(
+                crate::error::validation_error(),
+                "UDA key cannot be empty or whitespace-only"
+            ));
+        }
+
+        let mut task = self.0.get_mut()?;
+        operations.with_inner_mut(|ops| {
+            task.remove_uda(&namespace, &key, ops)
+        })?;
+        Ok(())
+    }
+
+}
+
+// Remove AsRef implementation as it doesn't work well with thread bounds
+// Use direct method calls instead
+
+impl From<TCTask> for Task {
+    fn from(value: TCTask) -> Self {
+        Task(ThreadBound::new(value))
+    }
+}
+
+pub fn init(module: &RModule) -> Result<(), Error> {
+    let class = module.define_class("Task", class::object())?;
+
+    // Property methods (Ruby idiomatic - no get_ prefix)
+    class.define_method("inspect", method!(Task::inspect, 0))?;
+    class.define_method("uuid", method!(Task::uuid, 0))?;
+    class.define_method("status", method!(Task::status, 0))?;
+    class.define_method("description", method!(Task::description, 0))?;
+    class.define_method("entry", method!(Task::entry, 0))?;
+    class.define_method("priority", method!(Task::priority, 0))?;
+    class.define_method("wait", method!(Task::wait, 0))?;
+    class.define_method("modified", method!(Task::modified, 0))?;
+    class.define_method("due", method!(Task::due, 0))?;
+    class.define_method("dependencies", method!(Task::dependencies, 0))?;
+
+    // Boolean methods with ? suffix
+    class.define_method("waiting?", method!(Task::waiting, 0))?;
+    class.define_method("active?", method!(Task::active, 0))?;
+    class.define_method("blocked?", method!(Task::blocked, 0))?;
+    class.define_method("blocking?", method!(Task::blocking, 0))?;
+    class.define_method("completed?", method!(Task::completed, 0))?;
+    class.define_method("deleted?", method!(Task::deleted, 0))?;
+    class.define_method("pending?", method!(Task::pending, 0))?;
+
+    // Tag methods
+    class.define_method("has_tag?", method!(Task::has_tag, 1))?;
+    class.define_method("tags", method!(Task::tags, 0))?;
+    class.define_method("annotations", method!(Task::annotations, 0))?;
+
+    // Value access - Ruby convention: no get_ prefix
+    class.define_method("value", method!(Task::get_value, 1))?;
+    class.define_method("get_value", method!(Task::get_value, 1))?;  // Keep for backward compatibility
+    class.define_method("uda", method!(Task::get_uda, 2))?;
+    class.define_method("get_uda", method!(Task::get_uda, 2))?;    // Keep for backward compatibility
+    class.define_method("udas", method!(Task::udas, 0))?;
+
+    // Mutation methods
+    class.define_method("set_description", method!(Task::set_description, 2))?;
+    class.define_method("set_status", method!(Task::set_status, 2))?;
+    class.define_method("set_priority", method!(Task::set_priority, 2))?;
+    class.define_method("add_tag", method!(Task::add_tag, 2))?;
+    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_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))?;
+    Ok(())
+}

data/ext/taskchampion/src/thread_check.rs

@@ -0,0 +1,61 @@
+use magnus::Error;
+use std::thread::ThreadId;
+use std::cell::RefCell;
+use crate::error::thread_error;
+
+pub struct ThreadBound<T> {
+    inner: RefCell<T>,
+    thread_id: ThreadId,
+}
+
+// SAFETY: ThreadBound ensures thread-local access only
+// The RefCell prevents concurrent access from the same thread
+// The thread_id check prevents access from different threads
+unsafe impl<T> Send for ThreadBound<T> {}
+unsafe impl<T> Sync for ThreadBound<T> {}
+
+impl<T> ThreadBound<T> {
+    pub fn new(inner: T) -> Self {
+        Self {
+            inner: RefCell::new(inner),
+            thread_id: std::thread::current().id(),
+        }
+    }
+
+    pub fn check_thread(&self) -> Result<(), Error> {
+        if self.thread_id != std::thread::current().id() {
+            return Err(Error::new(
+                thread_error(),
+                "Object cannot be accessed from a different thread",
+            ));
+        }
+        Ok(())
+    }
+
+    pub fn get(&self) -> Result<std::cell::Ref<T>, Error> {
+        self.check_thread()?;
+        Ok(self.inner.borrow())
+    }
+
+    pub fn get_mut(&self) -> Result<std::cell::RefMut<T>, Error> {
+        self.check_thread()?;
+        Ok(self.inner.borrow_mut())
+    }
+
+    pub fn into_inner(self) -> Result<T, Error> {
+        if self.thread_id != std::thread::current().id() {
+            return Err(Error::new(
+                thread_error(),
+                "Object cannot be extracted from a different thread",
+            ));
+        }
+        Ok(self.inner.into_inner())
+    }
+}
+
+#[macro_export]
+macro_rules! check_thread {
+    ($self:expr) => {
+        $self.0.check_thread()?;
+    };
+}

data/ext/taskchampion/src/util.rs

@@ -0,0 +1,131 @@
+use magnus::{Error, Value, RString, RHash, RArray, IntoValue, prelude::*};
+use taskchampion::Uuid;
+use chrono::{DateTime, Utc};
+use std::collections::HashMap;
+use crate::error::validation_error;
+
+/// Convert a string from Ruby into a Rust Uuid with enhanced validation
+pub fn uuid2tc(s: impl AsRef<str>) -> Result<Uuid, Error> {
+    let uuid_str = s.as_ref();
+    Uuid::parse_str(uuid_str)
+        .map_err(|_| Error::new(
+            validation_error(),
+            format!("Invalid UUID format: '{}'. Expected format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", uuid_str)
+        ))
+}
+
+/// Convert a taskchampion::Error into a Ruby error with enhanced mapping
+pub fn into_error(err: taskchampion::Error) -> Error {
+    crate::error::map_taskchampion_error(err)
+}
+
+/// Convert Rust DateTime<Utc> to Ruby DateTime
+pub fn datetime_to_ruby(dt: DateTime<Utc>) -> Result<Value, Error> {
+    let ruby = magnus::Ruby::get().map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+    let datetime_class: Value = ruby.eval("require 'date'; DateTime")?;
+
+    // Convert to string and parse in Ruby (simplest approach)
+    let iso_string = dt.to_rfc3339();
+    datetime_class.funcall("parse", (iso_string,))
+}
+
+/// Convert Ruby DateTime/Time/String to Rust DateTime<Utc> with enhanced validation
+pub fn ruby_to_datetime(value: Value) -> Result<DateTime<Utc>, Error> {
+    let ruby = magnus::Ruby::get().map_err(|e| Error::new(magnus::exception::runtime_error(), e.to_string()))?;
+
+    // If it's a string, parse it
+    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)))
+            .map_err(|_| Error::new(
+                validation_error(),
+                format!("Invalid datetime format: '{}'. Expected ISO 8601 format (e.g., '2023-01-01T12:00:00Z') or '%Y-%m-%d %H:%M:%S %z'", s)
+            ))
+    } else {
+        // Convert Ruby DateTime/Time to ISO string then parse
+        match value.funcall::<_, (), String>("iso8601", ()) {
+            Ok(iso_string) => {
+                DateTime::parse_from_rfc3339(&iso_string)
+                    .map(|dt| dt.with_timezone(&Utc))
+                    .map_err(|_| Error::new(
+                        validation_error(),
+                        format!("Invalid datetime from Ruby object: '{}'. Unable to parse as ISO 8601", iso_string)
+                    ))
+            }
+            Err(_) => Err(Error::new(
+                validation_error(),
+                format!("Cannot convert value to datetime. Expected Time, DateTime, or String, got: {}", value.class().inspect())
+            ))
+        }
+    }
+}
+
+/// Convert Option<T> to Ruby value (nil for None)
+pub fn option_to_ruby<T, F>(opt: Option<T>, converter: F) -> Result<Value, Error>
+where
+    F: FnOnce(T) -> Result<Value, Error>,
+{
+    match opt {
+        Some(val) => converter(val),
+        None => Ok(().into_value()), // () converts to nil in Magnus
+    }
+}
+
+/// Convert Ruby value to Option<T> (nil becomes None)
+pub fn ruby_to_option<T, F>(value: Value, converter: F) -> Result<Option<T>, Error>
+where
+    F: FnOnce(Value) -> Result<T, Error>,
+{
+    if value.is_nil() {
+        Ok(None)
+    } else {
+        converter(value).map(Some)
+    }
+}
+
+/// Convert HashMap to Ruby Hash
+pub fn hashmap_to_ruby(map: HashMap<String, String>) -> Result<RHash, Error> {
+    let hash = RHash::new();
+    for (k, v) in map {
+        hash.aset(k, v)?;
+    }
+    Ok(hash)
+}
+
+/// Convert Ruby Hash to HashMap
+pub fn ruby_to_hashmap(hash: RHash) -> Result<HashMap<String, String>, Error> {
+    let mut map = HashMap::new();
+    hash.foreach(|key: String, value: String| {
+        map.insert(key, value);
+        Ok(magnus::r_hash::ForEach::Continue)
+    })?;
+    Ok(map)
+}
+
+/// Convert Vec to Ruby Array
+pub fn vec_to_ruby<T, F>(vec: Vec<T>, converter: F) -> Result<RArray, Error>
+where
+    F: Fn(T) -> Result<Value, Error>,
+{
+    let array = RArray::with_capacity(vec.len());
+    for item in vec {
+        array.push(converter(item)?)?;
+    }
+    Ok(array)
+}
+
+/// Convert Ruby Array to Vec
+pub fn ruby_to_vec<T, F>(array: RArray, converter: F) -> Result<Vec<T>, Error>
+where
+    F: Fn(Value) -> Result<T, Error>,
+{
+    let mut vec = Vec::with_capacity(array.len());
+    for i in 0..array.len() {
+        let value: Value = array.entry(i as isize)?;
+        vec.push(converter(value)?);
+    }
+    Ok(vec)
+}

data/ext/taskchampion/src/working_set.rs

@@ -0,0 +1,72 @@
+use magnus::{
+    class, method, prelude::*, Error, IntoValue, RModule, Value,
+};
+use std::sync::Arc;
+use taskchampion::WorkingSet as TCWorkingSet;
+
+use crate::thread_check::ThreadBound;
+
+#[magnus::wrap(class = "Taskchampion::WorkingSet", free_immediately)]
+pub struct WorkingSet(ThreadBound<Arc<TCWorkingSet>>);
+
+impl WorkingSet {
+    pub fn from_tc_working_set(tc_working_set: Arc<TCWorkingSet>) -> Self {
+        WorkingSet(ThreadBound::new(tc_working_set))
+    }
+
+    fn largest_index(&self) -> Result<usize, Error> {
+        let working_set = self.0.get()?;
+        Ok(working_set.largest_index())
+    }
+
+    fn by_index(&self, index: usize) -> Result<Value, Error> {
+        let working_set = self.0.get()?;
+        match working_set.by_index(index) {
+            Some(uuid) => {
+                // For now, return the UUID string - we'll need to solve the task lookup problem
+                // in a different way since WorkingSet doesn't have access to the replica
+                Ok(uuid.to_string().into_value())
+            }
+            None => Ok(().into_value()),
+        }
+    }
+    fn by_uuid(&self, uuid: String) -> Result<Value, Error> {
+        let working_set = self.0.get()?;
+        let tc_uuid = crate::util::uuid2tc(&uuid)?;
+
+        match working_set.by_uuid(tc_uuid) {
+            Some(index) => Ok(index.into_value()),
+            None => Ok(().into_value()),
+        }
+    }
+
+    fn renumber(&self) -> Result<(), Error> {
+        let _working_set = self.0.get()?;
+        // Note: renumber requires &mut self in TaskChampion, but WorkingSet is immutable
+        // This is a limitation we'll need to work around or document
+        Err(Error::new(
+            magnus::exception::runtime_error(),
+            "WorkingSet renumber is not implemented due to mutability constraints",
+        ))
+    }
+
+    fn inspect(&self) -> Result<String, Error> {
+        let working_set = self.0.get()?;
+        Ok(format!(
+            "#<Taskchampion::WorkingSet: largest_index={}>",
+            working_set.largest_index()
+        ))
+    }
+}
+
+pub fn init(module: &RModule) -> Result<(), Error> {
+    let class = module.define_class("WorkingSet", class::object())?;
+
+    class.define_method("largest_index", method!(WorkingSet::largest_index, 0))?;
+    class.define_method("by_index", method!(WorkingSet::by_index, 1))?;
+    class.define_method("by_uuid", method!(WorkingSet::by_uuid, 1))?;
+    class.define_method("renumber", method!(WorkingSet::renumber, 0))?;
+    class.define_method("inspect", method!(WorkingSet::inspect, 0))?;
+
+    Ok(())
+}

data/lib/taskchampion/version.rb

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

data/lib/taskchampion.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "taskchampion/version"
+require_relative "taskchampion/taskchampion" # This loads the Rust extension
+
+module Taskchampion
+  # Error classes are defined in Rust
+  # Replica class is defined in Rust
+  # Additional Ruby-level helpers can be added here
+
+  # Override WorkingSet to add task lookup functionality
+  class WorkingSet
+    # Store replica reference for task lookup
+    attr_accessor :replica
+
+    alias_method :_original_by_index, :by_index
+
+    def by_index(index)
+      uuid_string = _original_by_index(index)
+      return nil if uuid_string.nil? || uuid_string.to_s.empty?
+
+      # If we have a replica reference, look up the actual task
+      if @replica
+        @replica.task(uuid_string)
+      else
+        uuid_string
+      end
+    end
+  end
+
+  # Override the Replica class to set the replica reference
+  class Replica
+    alias_method :_original_working_set, :working_set
+
+    def working_set
+      ws = _original_working_set
+      ws.replica = self
+      ws
+    end
+  end
+end