tom_worktracker_core

Published on pub.dev as tom_worktracker_core 1.1.0.

Attribution. The Tom Framework is developed by Peter Nicolai Alexis Kyaw. This package is BSD-3-Clause licensed and published on pub.dev.

Worktracker's core: workspace and todo-world discovery, the read pipeline (snapshot → graph → projections), the mutation API, bundles and execution tracking over a workspace's *.todo.yaml files.

The todo model and the file codec it works with are not here: they are the published package tom_todo_model (repository tom_modules), which Worktracker, Webwork and the VS Code scripting API all share. Its README describes TomTodo, the statuses and priorities, the splice codec (TomTodoFile), the date-code ids, the decisions journal and archive / delete as relocation.

Entry point

An application that only needs todos depends on tom_todo_model alone, which touches no file system, so a browser build can link it.

Worktracker

TodoDocumentReader and TodoDocumentStore read a workspace's todo files through tom_todo_model's codec and write an edit back in the file's own encoding; WorktrackerMutationApi creates, edits, moves through the status transitions (WorktrackerStatusTransitions), deletes and links todos, stamping updated on every change. The read pipeline builds the graph, the execution and Gantt projections, and the bundle plan from the snapshot.

Example

The shared model in use, as Worktracker reads and edits a file through it:

import 'package:tom_todo_model/tom_todo_model.dart';

const source = '''# Garden todos
quest: garden
todos:
  - id: gx1_ajka-plant
    title: Plant the beds
    # Started on Monday.
    description: Plant the spring beds.
    status: in-progress
''';

void main() {
  var file = TomTodoFile.parse(source);
  final todo = file.todos.single;
  print('${todo.id}: ${todo.status.wire}');

  final done = todo.copy()
    ..changeStatus(
      TomTodoStatus.completed,
      on: DateTime.utc(2026, 10, 21),
      by: 'ada',
    );
  var text = file.withTodo(0, done);
  print(
    text.contains('# Started on Monday.') ? 'comment kept' : 'comment lost',
  );

  file = TomTodoFile.parse(text);
  final next = tomMintTodoId('gx2', DateTime(2026, 10, 21, 9), slug: 'Water');
  text = file.withInserted(TomTodo(id: next, title: 'Water the beds'));
  print(next);

  final plan = tomPlanTodoRelocation(
    source: TomTodoFile.parse(text),
    fileName: 'todos.garden.todo.yaml',
    index: 0,
    kind: TomTodoRelocationKind.archive,
    now: DateTime.utc(2026, 10, 21),
  );
  print(
    tomTodoSiblingName('todos.garden.todo.yaml', TomTodoRelocationKind.archive),
  );
  print(TomTodoFile.parse(plan.sourceText).todos.map((t) => t.id).join(', '));
}

The compiled form of this section is example/todo_file_example.dart, and test/readme_example_test.dart asserts what it prints.

Dependencies

Status

Version 1.1.0. dart test runs the suite: Worktracker's discovery, graph, projections, mutation API, bundles and execution tracking, and the example. The model's and the codec's own tests are in tom_todo_model.