3ca4c5291d
The kanban board is now a proper tool alongside migration-analyser. Adds tools/kanban/project.xml (blaise-kanban module) and registers it in the root aggregator. Removes the standalone build.sh script since PasBuild handles compilation.
121 lines
3.3 KiB
Plaintext
121 lines
3.3 KiB
Plaintext
= Kanban TUI — A Terminal Task Board
|
|
|
|
A three-column Kanban board for the terminal, written entirely in Blaise Pascal.
|
|
|
|
== Features
|
|
|
|
* Three fixed columns: *Todo*, *In Progress*, *Done*
|
|
* Add, delete, and move tasks with single-key shortcuts
|
|
* Per-task detail files (multi-line notes via `$EDITOR`)
|
|
* Priority tagging (high/low) with visual indicators
|
|
* Human-readable `.kanban` file format (works with grep, git, etc.)
|
|
* Pure Pascal — no C code, no external libraries beyond libc
|
|
* Box-drawing characters and ANSI colour output
|
|
* Vim-style keybindings (hjkl navigation)
|
|
|
|
== Building
|
|
|
|
[source,bash]
|
|
----
|
|
./build.sh [path-to-blaise-compiler]
|
|
----
|
|
|
|
The build script compiles the Blaise source to QBE IR, assembles it, and links the final binary.
|
|
|
|
== Usage
|
|
|
|
=== Interactive (TUI) mode
|
|
|
|
[source,bash]
|
|
----
|
|
./kanban # uses ./board.kanban
|
|
./kanban myproject.kanban
|
|
----
|
|
|
|
=== CLI mode
|
|
|
|
Add tasks without launching the TUI:
|
|
|
|
[source,bash]
|
|
----
|
|
./kanban board.kanban --add "Fix the parser bug"
|
|
./kanban board.kanban --add "Urgent fix" --priority high
|
|
./kanban board.kanban --add "WIP item" --status progress
|
|
./kanban board.kanban --add "Task" --detail "Multi-line detail text here"
|
|
./kanban board.kanban --add "Task" --detail-file notes.txt
|
|
----
|
|
|
|
[cols="1,3"]
|
|
|===
|
|
| Option | Description
|
|
|
|
| `--add "title"` | Add a new task (required for CLI mode)
|
|
| `--detail "text"` | Set inline detail text for the new task
|
|
| `--detail-file path` | Read detail text from a file
|
|
| `--priority high\|low` | Set task priority
|
|
| `--status todo\|progress\|done` | Set initial status (default: todo)
|
|
| `--help`, `-h` | Show usage information
|
|
|===
|
|
|
|
== Keybindings
|
|
|
|
[cols="1,3"]
|
|
|===
|
|
| Key | Action
|
|
|
|
| `j` / `k` | Move cursor up / down
|
|
| `Tab` / arrows | Switch columns
|
|
| `a` | Add a new task to the current column
|
|
| `d` | Delete the selected task
|
|
| `h` | Move task left (toward Todo)
|
|
| `l` | Move task right (toward Done)
|
|
| `p` | Cycle priority (none -> high -> low)
|
|
| `Enter` | Open detail view for the selected task
|
|
| `?` | Show help
|
|
| `q` | Save and quit
|
|
|===
|
|
|
|
=== Detail View
|
|
|
|
| Key | Action
|
|
|
|
| `j` / `k` | Scroll up / down
|
|
| `e` | Edit detail in `$EDITOR` (defaults to nano)
|
|
| `Esc` | Return to board
|
|
|
|
== Data Format
|
|
|
|
The `.kanban` file is a simple, human-readable text format:
|
|
|
|
[source]
|
|
----
|
|
#next-id: 8
|
|
|
|
## Todo
|
|
- 5 | Add UTF-8 lexer support | priority:high | created:2026-06-01
|
|
- 6 | Benchmark hash map | created:2026-06-03
|
|
|
|
## In Progress
|
|
- 3 | TUI Kanban app | priority:high | created:2026-06-05
|
|
|
|
## Done
|
|
- 1 | Bootstrap compiler | created:2026-05-20
|
|
----
|
|
|
|
Per-task detail files are stored in a `.kanban.d/` subdirectory alongside the `.kanban` file, named by task ID (e.g., `board.kanban.d/3.txt`).
|
|
Detail files only exist for tasks that have notes — no empty placeholders.
|
|
|
|
== Architecture
|
|
|
|
[cols="1,3"]
|
|
|===
|
|
| File | Role
|
|
|
|
| `kanban_app.pas` | Main program — parses args, wires components, runs the UI
|
|
| `kanban.terminal.pas` | Terminal abstraction — raw mode, key reading, ANSI output, box drawing
|
|
| `kanban.data.pas` | Data model — load/save `.kanban` files, manage tasks and detail files
|
|
| `kanban.ui.pas` | TUI rendering and input handling — board view, detail view, input mode
|
|
|===
|
|
|
|
The terminal unit uses `external name` bindings to POSIX functions (`tcgetattr`, `tcsetattr`, `ioctl`, `read`) for raw terminal control — no C shim required.
|