tom_worktracker_core 1.1.0

Worktracker core: the workspace discovery, graph, projections and mutation API over the *.todo.yaml files (the todo model itself is tom_todo_model).

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

Import	Holds	Platforms
package:tom_worktracker_core/tom_worktracker_core.dart	Worktracker: settings, world and workspace discovery, the document reader and store, the read pipeline, the mutation API, bundles and execution tracking	Dart VM (reads the file system)

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

Dependency	Kind	For
tom_todo_model	runtime	the todo model and the *.todo.yaml codec
tom_basics	runtime	text decoding that keeps a file's encoding, used by the document reader and store
yaml	runtime	reading settings and todo worlds
meta, path	runtime	annotations; Worktracker's paths
test, lints	dev	the suite

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.