Developer Guide

Installing mise

Install mise:

curl https://mise.run | sh

Activate it in your shell:

# zsh
echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"

# bash
echo 'eval "$(mise activate bash)"' >> ~/.bashrc

# fish
echo 'mise activate fish | source' >> ~/.config/fish/config.fish

Restart your shell, then install this project’s tools:

mise install

The rest of this guide assumes mise is activated in your shell, so the toolchain and project environment from .config/mise.toml are available automatically. Pinned values like the Taskwarrior source tag and testdata ref live there, while the task entrypoints themselves live in .config/mise/tasks/taskwarrior-tui/.

Running Tests

git clone https://github.com/kdheepak/taskwarrior-tui
cd taskwarrior-tui

mise run taskwarrior-tui:cargo-test

mise run taskwarrior-tui:cargo-test fetches taskwarrior-testdata at a pinned commit for deterministic runs.

Building the CLI

cargo build
cargo build --release

Running a Debug Build

cargo run

Running the TUI with Local Fixture Data

Import tests/data/export.json into tests/data/.task:

mise run taskwarrior-tui:import-taskdata

Run the TUI against that imported data and remove tests/data/.task when the TUI exits:

mise run taskwarrior-tui:run-taskdata

Use a release build instead:

mise run taskwarrior-tui:run-taskdata --release

Remove tests/data/.task without starting the TUI:

mise run taskwarrior-tui:clean-taskdata

Running a Release Build

cargo run --release

Testing an Individual Function

If you want to test the test_taskwarrior_timing function in src/app.rs:

mise run taskwarrior-tui:setup-testdata
cargo test -- app::tests::test_taskwarrior_timing --nocapture

Getting Logs

With mise activated, TASKWARRIOR_TUI_LOG_LEVEL=debug is already set for this repo.

taskwarrior-tui

# OR

cargo run

Contributing to Documentation

The Starlight site lives in docs/. Content pages live in docs/src/content/docs/. Packaging assets that used to live alongside the docs now live in packaging/.

Build the docs locally with:

mise run taskwarrior-tui:docs-build

For iterative docs work, install the site dependencies once and start the Astro dev server:

mise run taskwarrior-tui:docs-preview

Regenerate the man page with:

mise run taskwarrior-tui:man

When you make a PR to the repository, a preview of the documentation is rendered and a link is posted to the PR.

Internals of taskwarrior-tui

taskwarrior-tui is a state-driven terminal user interface. Keyboard events are read asynchronously and communicated using channels. Most of the logic is implemented in src/app.rs. The difference between the previous state and the current state of the TUI is rendered every Tick by ratatui. The app.draw_... functions are responsible for rendering the UI. Actions for key presses are taken in app.handle_input(&mut self, input: Key).