taskchampion-rb 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b267de15e0004e931e2a46f37f9014afe8fdc52e58e675190dab990cb345e75
-  data.tar.gz: 6a84efc5a165c428c67e6d50f3ce0b001eab4d3fde464ffed123d218aaf04033
+  metadata.gz: cafd2930e70aef0ac31c03c98e3d806cd1fba49408ce69b4bcb5d41074465c3f
+  data.tar.gz: 23b8948a759f8cc7b28e2cb68d65d40750943bd05bf127a87f5e25bf80116900
 SHA512:
-  metadata.gz: ff860c7dcb85bc6a04aced731b403072a03c3a222f869fec0a25af1436b14fb67e4df0a9dc5cfad4d829b1fe1f39936e6df07c90605eb859202ac8f80fc8a17f
-  data.tar.gz: d826c3704fec6432e872abe24423d92e04da810c0718ce0cc224dbddd780b2279b336c635bd1e285405bd4534710fbd9928bf4ee7c5f225f4118baade8315436
+  metadata.gz: 2ff558c7674c2ff686e08ec9e220baa966edf438353e42832a566771cbcb2348c329d34fa27937b7bc9b71c0fdd7721f6e3086a675a5baa4e54f2e4e102600a5
+  data.tar.gz: 34dfcc7ea08bc2f90b846d3a19b1526731a0142d1cc6d09a867923bd6620be3abc13602eab12f8022c85dfc10b3f97502c62419808db3b942808489efbd51488

data/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+### Building the gem
+```bash
+bundle install
+bundle exec rake compile  # Compiles the Rust extension
+```
+
+### Running tests
+```bash
+bundle exec rake test              # Run all tests
+bundle exec rake test TEST=test/test_replica.rb  # Run specific test file
+```
+
+### Linting
+```bash
+bundle exec rake rubocop           # Run RuboCop linter
+```
+
+### Publishing new version
+```bash
+rake publish[patch]  # Bump patch version and release
+rake publish[minor]  # Bump minor version and release
+rake publish[major]  # Bump major version and release
+```
+
+## Architecture Overview
+
+This is a Ruby gem that provides bindings to TaskChampion (Rust library) for task management. The architecture consists of:
+
+### Key Components
+
+1. **Rust Extension** (`ext/taskchampion/`)
+   - Written in Rust using Magnus for Ruby-Rust interop
+   - Entry point: `ext/taskchampion/src/lib.rs`
+   - Implements core classes: Replica, Task, WorkingSet, Operations, etc.
+   - Thread safety enforced via `thread_check.rs` - objects can only be accessed from their creation thread
+
+2. **Ruby Layer** (`lib/taskchampion.rb`)
+   - Thin wrapper that loads the Rust extension
+   - Extends WorkingSet and Replica classes with Ruby-specific convenience methods
+   - Maintains Ruby idioms (snake_case methods, `?` suffix for booleans)
+
+3. **Core Classes**
+   - `Replica`: Main database interface for task storage (in-memory or on-disk)
+   - `Task`: Individual task with properties and methods
+   - `Operations`: Collection of operations for batch changes
+   - `WorkingSet`: Active subset of tasks
+   - `DependencyMap`: Task dependency management
+   - Error hierarchy: Error → ThreadError, StorageError, ValidationError, ConfigError
+
+### Testing Structure
+- Uses Minitest framework
+- Tests organized in `test/unit/`, `test/integration/`, and `test/performance/`
+- Base test class: `TaskchampionTest` in `test/test_helper.rb`
+- Tests use temporary directories for file-based replicas
+
+### Ruby API Design Principles
+- Methods use snake_case (not get_/set_ prefixes)
+- Boolean methods end with `?`
+- Symbols for enums (`:pending`, `:completed`, `:read_only`)
+- `nil` instead of None
+- Keyword arguments for optional parameters

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'taskchampion'
+require 'securerandom'
+
+# Create an in-memory replica
+replica = Taskchampion::Replica.new_in_memory
+
+# Create several tasks with different statuses
+puts "Creating tasks..."
+
+# Create pending tasks
+3.times do |i|
+  ops = Taskchampion::Operations.new
+  task = replica.create_task(SecureRandom.uuid, ops)
+  task.set_description("Pending task #{i + 1}", ops)
+  task.set_status(Taskchampion::PENDING, ops)
+  replica.commit_operations(ops)
+  puts "  Created pending task: #{task.description}"
+end
+
+# Create completed tasks
+2.times do |i|
+  ops = Taskchampion::Operations.new
+  task = replica.create_task(SecureRandom.uuid, ops)
+  task.set_description("Completed task #{i + 1}", ops)
+  task.set_status(Taskchampion::COMPLETED, ops)
+  replica.commit_operations(ops)
+  puts "  Created completed task: #{task.description}"
+end
+
+# Create a deleted task
+ops = Taskchampion::Operations.new
+task = replica.create_task(SecureRandom.uuid, ops)
+task.set_description("Deleted task", ops)
+task.set_status(Taskchampion::DELETED, ops)
+replica.commit_operations(ops)
+puts "  Created deleted task: #{task.description}"
+
+puts "\n" + "=" * 50
+puts "Getting pending tasks..."
+puts "=" * 50
+
+# Use the pending_tasks method to get only pending tasks
+pending = replica.pending_tasks
+
+puts "\nFound #{pending.length} pending tasks:"
+pending.each_with_index do |task, index|
+  puts "  #{index + 1}. [#{task.uuid[0..7]}...] #{task.description}"
+  puts "     Status: #{task.status}"
+  puts "     Active: #{task.active?}"
+end
+
+puts "\n" + "=" * 50
+puts "For comparison, all_tasks returns #{replica.all_tasks.size} tasks total"

data/ext/taskchampion/src/replica.rs

@@ -260,6 +260,20 @@ impl Replica {
 
         Ok(tc_replica.num_undo_points().map_err(into_error)?)
     }
+
+    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)
+    }
 }
 
 pub fn init(module: &RModule) -> Result<(), Error> {
@@ -285,6 +299,7 @@ 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("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(
@@ -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.5.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.5.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
@@ -36,6 +36,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - Cargo.lock
 - Cargo.toml
 - README.md
@@ -44,10 +45,12 @@ files:
 - docs/THREAD_SAFETY.md
 - docs/breakthrough.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
 - ext/taskchampion/Cargo.toml
 - ext/taskchampion/extconf.rb