Expose operations from TaskChampion

[djmitche]

Background

Every change to a task is represented internally as an "Operation" https://github.com/GothenburgBitFactory/taskwarrior/blob/41992d484909bd865bc252e99e588c5c3f37c71a/taskchampion/taskchampion/src/storage/op.rs#L10-L38 This is how we accomplish task sync -- different replicas share the set of operations they have applied, and resolve any conflicts in a reasonable, consistent way.

Note that a single command-line invocation may produce several operations. For example

task 123 start +inprogress prio:M

would create four Update operations: one to set the start property to the current time, one to add the tag_inprogress property, one to set the priority property to M and one to update the modified property to the current time.

There are also UndoPoint operations, which do not actually change anything but act as a signpost for how many operations to revert when running task undo -- that command basically reverts operations until it reaches an UndoPoint. The UndoPoint operations are not sent to the server.

Once operations are successfully sent to the server, they are no longer stored locally. This avoids the local task database growing forever.

Currently, none of this is visible in Taskchampion's public API. This bug would change that.

Motivation

We'll need this for a few reasons:

The task undo command previously showed a "diff" of what it would change, and asked the user for permission. This is not possible with the current Taskchampion API (see https://github.com/GothenburgBitFactory/taskwarrior/commit/4b814bc602a365342a7ebb101c8d156f8cd4a15a). But if there was a way to query Taskchampion to say "hey, what are the operations back to the latest UndoPoint?" then it could generate a diff view from that.

The task info command has historically used the undo information to show the history for a particular task. This operated by scanning the entire undo history for records matching that task's uuid, and formatting those nicely for display. Again, that's currently impossible (support was removed in GothenburgBitFactory/taskwarrior#3060). If there was a way to query Taskchampion to say "hey, what operations have happened for this task?" then we could bring back that functionality.

Looking forward, one of the things we've considered in GothenburgBitFactory/taskchampion#372 is to allow a user of the Taskchampion API to provide a list of operations to apply, instead of calling methods like task.start(..) or task.set_description(..). A different possibility we've considered is that a user of the Taskchampion API could call methods like task.start(..) or task.set_description(..) and build up a list of operations, then "commit" those all at once. This would allow the task command to confirm changes with the user before committing them, for example. All of this paragraph is out of scope for this issue, but should be kept in mind when designing the API.

Details

Off the top of my head, I think this can be broken into two parts:

Operations for Undo

• Making the ReplicaOp type public
• Defining an API on the Replica type for fetching all operations back to the latest UndoPoint, and implementing that through the storage layer.
• Adding a C interface in taskchampion-lib
• Adding a C++ interface
• Writing some C++ support for printing a list of operations as a "diff"
• Using this for confirmation of task undo

Operations for Info

all of the above, and..

• Updating the Taskchampion storage backend to store operations for each task for as long as that task exists. This is different from just storing all operations in the order they occurred, because once a task is deleted we want to also delete its associated operations. This will require changing the database schema.
• Making that information available from the Replica type
• Adding a C interface in taskchampion-lib
• Adding a C+ interface
• Using this to show a task's history in task info when the journal.info config is enabled.

[djmitche]

@masaeedu is considering working on this, so I'll un-assign from myself.

[djmitche]

@ryneeverett I think this is done -- is there anything more to do?

[ryneeverett]

Yes, GothenburgBitFactory/taskwarrior#3213 only addressed the "Operations for Undo" section of your detailed breakdown. "Operations for Info" has not yet been addressed.

[djmitche]

Right, thank you!

[djmitche]

Status update: #372 has handled making operations a first-class thing in TaskChampion (not just for undo). What remains for this issue is:

• Store operations for all tasks, even after those operations are sync'd
• Provide an API to access those operations

Then Taskwarrior can read those operations and construct a journal in the task info command.