Compare commits

..
2 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 c1137f29cf (1b78a24) Scroll the tui detail view on pgup and pgdn, and bump to 0.7.1
The detail view had no scrolling at all: no offset on Board, nothing passed
to Paragraph::scroll, so anything past the height of the overlay was
unreachable. Every ticket in this repo is longer than that. The footer read
"↑↓ scroll" while up and down moved the selection, so it named a key that did
nothing and sent the reader looking for their own mistake.

The scroll goes on pgup and pgdn rather than taking up and down. Up and down
stay on the selection with the modal open, so a whole column can be read
without closing it and the modal follows the selection. That is worth more
than the two keys.

The offset is clamped against the wrapped line count from
Paragraph::line_count, which is why ratatui now carries the
unstable-rendered-line-info feature. The paragraph wraps on words, so a clamp
on the raw lines would stop short of the end or run past it into blank space,
and counting the wrapping by hand would only agree with the widget until one
of the two changed. The clamp runs on the keypress and again in the draw,
since the terminal can be resized between them and a tick can shorten the
ticket under a reader who is already at the end.

The offset resets when the selection moves and when the modal is closed, so a
ticket opens at its top. It deliberately does not reset on a tick: an edit
elsewhere in the tree must not throw the reader back to the top of what they
are reading.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 12:38:54 +02:00
Ansho ReiandClaude Opus 5 77bf2d9e2a Say when to move a ticket, not just how
Both AGENTS.md and the kanban skill listed the statuses and the mv command
without ever saying at what point to run it, so a ticket could sit in backlog
until the work was finished and the board said nothing while it was in progress.
That is what happened to f6af387.

The rule is now in both places, and in both for a reason: the skill is what an
agent loads to work tickets in any repo, and AGENTS.md is what an agent working
on worklane itself reads, possibly without ever loading the skill. The skill's
Workflow section also becomes a sequence for working one ticket rather than an
unordered list of commands, with the command list kept separately.

Worth stating because it is self-enforcing: only one stage forward is allowed at
a time, so a ticket left in backlog cannot go straight to reviewing and has to
be walked through committed regardless. Moving it up front is the same two
commands in a more useful order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-21 11:54:23 +02:00
7 changed files with 354 additions and 20 deletions
+25 -8
View File
@@ -176,12 +176,29 @@ worklane comment "My Ticket" "Needs changes to the UI"
worklane comment a1b2c3d4 "LGTM, approved"
```
## Workflow
## Working a ticket
1. Use `worklane add` to create tickets with all relevant details
2. Use `worklane ls [status]` to view tickets by status
3. Use `worklane show <id>` to view full ticket details
4. Use `worklane mv <id> --status <target>` to move tickets through the workflow
5. Use `worklane set <ticket>` to correct a field, or `worklane append <ticket>` to add to a section
6. Use `worklane check <ticket> <n>` to tick a criterion as it is met
7. Use `worklane comment <ticket> <body>` to add notes to tickets
Move the ticket as you work it, not afterwards. The board should say what is happening
now, not only what already landed.
1. `worklane show <id>` to read it
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
the ticket as being worked on, so it belongs at the start
3. Do the work. `worklane check <id> <n>` as each criterion is met
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
acceptance criterion, something the ticket got wrong
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
makes moving it up front the same two commands in a more useful order.
## Commands
- `worklane add` creates tickets with all relevant details
- `worklane ls [status]` views tickets by status
- `worklane show <id>` views full ticket details
- `worklane mv <id> --status <target>` moves tickets through the workflow
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
- `worklane check <ticket> <n>` ticks a criterion as it is met
- `worklane comment <ticket> <body>` adds notes to tickets
+14
View File
@@ -20,6 +20,15 @@
## Status Workflow
`backlog` → `committed` → `reviewing` → `done`
**Move the ticket as you work it, not afterwards.** `mv <id> --status committed` before
writing any code, and `mv <id> --status reviewing` once it is done and the tests pass.
The board is then true while the work is in progress, not only after it lands, which is
the whole point of having a `committed` column.
Only one stage at a time is allowed, so a ticket left in `backlog` until the end cannot
go straight to `reviewing` and has to be walked through `committed` anyway. Doing it up
front is the same two commands in a more useful order.
## Testing
- Run: `cargo test`
- Tests use `assert_cmd` and `assert_fs` for CLI testing
@@ -74,6 +83,11 @@
- The digest guards the *rescan*, not the draw. ratatui diffs its buffer, so drawing every iteration is free; reading the tree every iteration is not
- `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
- Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view
- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
- **The footer names only keys that work.** It read `↑↓ scroll` when nothing scrolled at all, which sends the reader looking for their own mistake. A UI that misdescribes itself is worse than one that is merely incomplete
- The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
Generated
+1 -1
View File
@@ -1494,7 +1494,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.7.0"
version = "0.7.1"
dependencies = [
"anyhow",
"assert_cmd",
+5 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.7.0"
version = "0.7.1"
edition = "2024"
[dependencies]
@@ -9,7 +9,10 @@ anyhow = "1"
uuid = { version = "1", features = ["v4"] }
chrono = { version = "0.4", features = ["serde"] }
libc = "0.2"
ratatui = "0.29"
# unstable-rendered-line-info for Paragraph::line_count, which is how the detail view
# knows where its text ends. Counting the wrapping by hand would only agree with the
# widget until one of us changed.
ratatui = { version = "0.29", features = ["unstable-rendered-line-info"] }
crossterm = "0.28"
[dev-dependencies]
+1 -1
View File
@@ -5,7 +5,7 @@ Worklane is a local Kanban flow for agentic software development.
## Commands
| Command | Description |
|---------|-------------|
| `worklane` or `worklane tui` | Opens the board: four status columns, redrawn when the tree changes. Read only. Arrows or `hjkl` to move, `enter` for detail, `q` to quit |
| `worklane` or `worklane tui` | Opens the board: four status columns, redrawn when the tree changes. Read only. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, `q` to quit |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories |
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>` |
+8
View File
@@ -141,6 +141,9 @@ fn run_tui(start: &std::path::Path) -> Result<()> {
board.tick()?;
terminal.draw(|frame| tui::draw(frame, &board))?;
// Taken after the draw, so a scroll measures the overlay that is on screen.
let screen = terminal.size()?;
// Bounded, so the tick still runs when nobody is typing.
if !event::poll(tui::POLL)? {
continue;
@@ -166,8 +169,13 @@ fn run_tui(start: &std::path::Path) -> Result<()> {
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(),
KeyCode::Left | KeyCode::Char('h') => board.select_column(-1),
KeyCode::Right | KeyCode::Char('l') => board.select_column(1),
// Up and down stay on the selection, open detail view or not, so a
// column can be read through without closing the modal. Scrolling the
// open ticket is a page at a time.
KeyCode::Up | KeyCode::Char('k') => board.select_card(-1),
KeyCode::Down | KeyCode::Char('j') => board.select_card(1),
KeyCode::PageUp => board.scroll_detail(-1, screen),
KeyCode::PageDown => board.scroll_detail(1, screen),
_ => {}
}
}
+300 -8
View File
@@ -12,7 +12,7 @@ use std::path::{Path, PathBuf};
use std::time::{Duration, SystemTime};
use anyhow::Result;
use ratatui::layout::{Constraint, Direction, Layout, Rect};
use ratatui::layout::{Constraint, Direction, Layout, Margin, Rect, Size};
use ratatui::style::{Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Borders, Clear, Paragraph, Wrap};
@@ -37,6 +37,8 @@ pub struct Board {
pub card: usize,
/// The body and comments of the selected ticket, when the detail view is open.
pub detail: Option<String>,
/// First visible line of the detail view, counted in wrapped lines.
pub offset: u16,
pub should_quit: bool,
worklane_dir: PathBuf,
digest: u64,
@@ -49,6 +51,7 @@ impl Board {
column: 0,
card: 0,
detail: None,
offset: 0,
should_quit: false,
worklane_dir: worklane_dir.to_path_buf(),
digest: 0,
@@ -87,6 +90,9 @@ impl Board {
self.clamp();
// The selected ticket may have moved or gone, so the open detail follows it.
// The scroll offset stays where the reader put it: an edit elsewhere in the tree
// should not throw them back to the top of what they are reading. A ticket that
// got shorter is caught by the clamp in the draw.
if self.detail.is_some() {
self.detail = self.selected().map(detail_of);
}
@@ -145,13 +151,38 @@ impl Board {
/// Open the detail view on the selected card, or close it if it is already open.
pub fn toggle_detail(&mut self) {
self.offset = 0;
self.detail = match self.detail {
Some(_) => None,
None => self.selected().map(detail_of),
};
}
/// Scroll the open detail view by whole screenfuls, one line kept for overlap.
///
/// Up and down move the selection, so the scroll is on PageUp and PageDown. That is
/// worth keeping either way: with the modal open, up and down step through the
/// tickets and the modal follows, so a column can be read without closing it.
///
/// Clamped against the wrapped text rather than the raw lines, so the last page ends
/// with the ticket instead of running on into blank space, and against zero at the
/// top. The screen is asked for because both ends belong to the overlay, which only
/// the draw otherwise measures.
pub fn scroll_detail(&mut self, pages: isize, screen: Size) {
let Some(detail) = &self.detail else { return };
let text = detail_text_area(Rect::new(0, 0, screen.width, screen.height));
// A screenful less a line, so the eye has something to land on after the jump.
let step = text.height.saturating_sub(1).max(1) as isize;
let last = last_offset(detail, text) as isize;
self.offset = (self.offset as isize + pages.saturating_mul(step)).clamp(0, last) as u16;
}
fn refresh_detail(&mut self) {
// A newly selected ticket starts at its top, not partway down where the last one
// was left.
self.offset = 0;
if self.detail.is_some() {
self.detail = self.selected().map(detail_of);
}
@@ -243,7 +274,7 @@ pub fn draw(frame: &mut Frame, board: &Board) {
draw_footer(frame, board, rows[1]);
if let Some(detail) = &board.detail {
draw_detail(frame, detail, area);
draw_detail(frame, detail, board.offset, area);
}
}
@@ -329,7 +360,7 @@ fn card_lines(ticket: &TicketItem, selected: bool) -> Vec<Line<'static>> {
fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) {
let keys = match board.detail {
Some(_) => " ↑↓ scroll enter close q quit ",
Some(_) => " ←→↑↓ select pgup/pgdn scroll enter close q quit ",
None => " ←→ column ↑↓ card enter detail q quit ",
};
@@ -339,16 +370,47 @@ fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) {
);
}
fn draw_detail(frame: &mut Frame, detail: &str, area: Rect) {
// Inset, so the board stays visible around the edges and the overlay reads as one.
/// Where the detail overlay sits in the frame.
///
/// Inset, so the board stays visible around the edges and the overlay reads as one.
fn detail_overlay(area: Rect) -> Rect {
let width = area.width.saturating_sub(area.width / 5).max(20);
let height = area.height.saturating_sub(area.height / 6).max(6);
let overlay = Rect {
Rect {
x: area.x + (area.width.saturating_sub(width)) / 2,
y: area.y + (area.height.saturating_sub(height)) / 2,
width: width.min(area.width),
height: height.min(area.height),
};
}
}
/// The part of the overlay that holds text: the border takes a row and a column on
/// either side, and the title sits on the top border rather than below it.
fn detail_text_area(area: Rect) -> Rect {
detail_overlay(area).inner(Margin::new(1, 1))
}
/// The furthest the detail view can scroll: the last screenful, and no further.
///
/// Measured by the widget rather than counted by hand, since it wraps on words. A clamp
/// on the raw lines would stop short of the end on a wrapped ticket, and one that
/// ignored the wrapping the other way would scroll past it into blank space.
fn last_offset(detail: &str, text: Rect) -> u16 {
let wrapped = Paragraph::new(detail)
.wrap(Wrap { trim: false })
.line_count(text.width);
u16::try_from(wrapped)
.unwrap_or(u16::MAX)
.saturating_sub(text.height)
}
fn draw_detail(frame: &mut Frame, detail: &str, offset: u16, area: Rect) {
let overlay = detail_overlay(area);
// Clamped here as well as on the keypress: the terminal may have been resized since,
// and a ticket read to its end can grow shorter under a tick.
let offset = offset.min(last_offset(detail, detail_text_area(area)));
let block = Block::default()
.borders(Borders::ALL)
@@ -362,7 +424,8 @@ fn draw_detail(frame: &mut Frame, detail: &str, area: Rect) {
frame.render_widget(
Paragraph::new(detail.to_string())
.block(block)
.wrap(Wrap { trim: false }),
.wrap(Wrap { trim: false })
.scroll((offset, 0)),
overlay,
);
}
@@ -397,6 +460,22 @@ mod tests {
path
}
/// A section of numbered lines, so a test can say which of them is on screen.
///
/// Long enough not to fit any overlay the tests draw, which is true of every real
/// ticket in the repo as well.
fn long_section(lines: usize) -> String {
let body: String = (1..=lines).map(|n| format!("Line {n:03}\n")).collect();
format!("\n## Notes\n{body}")
}
/// The screen the scrolling tests draw on, so the keypress and the draw measure the
/// same overlay.
const SCREEN: Size = Size {
width: 120,
height: 20,
};
/// The rendered buffer as lines of text, escapes and styling dropped.
fn render(board: &Board, width: u16, height: u16) -> Vec<String> {
let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap();
@@ -658,6 +737,219 @@ mod tests {
assert!(!board.tick().unwrap());
}
/// The reported bug: a ticket longer than the overlay had no way to be read past its
/// first screenful, comments included.
#[test]
fn paging_down_reaches_the_end_of_a_long_ticket() {
let dir = board_dir();
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", &long_section(60));
let comments = dir.join("comments").join(uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
"**Comment**\nThe last word.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
let top = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(top.contains("A description."), "not at the top:\n{top}");
assert!(!top.contains("Line 060"), "the fixture is too short:\n{top}");
// More pages than the ticket has, since the clamp is what stops it.
for _ in 0..20 {
board.scroll_detail(1, SCREEN);
}
let end = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(end.contains("Line 060"), "the end is out of reach:\n{end}");
assert!(end.contains("The last word."), "the comments are out of reach:\n{end}");
assert!(!end.contains("A description."), "nothing scrolled:\n{end}");
}
/// The end of the scroll is the end of the text, not blank space past it, and the top
/// of it is the top of the ticket.
#[test]
fn the_scroll_offset_stops_at_both_ends() {
let dir = board_dir();
write_ticket(
&dir,
"backlog",
"11111111-0000-4000-8000-000000000000",
"First one",
&long_section(60),
);
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
for _ in 0..20 {
board.scroll_detail(1, SCREEN);
}
let settled = board.offset;
assert!(settled > 0, "a long ticket did not scroll at all");
board.scroll_detail(1, SCREEN);
assert_eq!(board.offset, settled, "the offset ran past the end");
// The last screenful is full: text on the bottom row of the overlay, not the
// blank space a clamp on the raw lines would have left there.
let lines = render(&board, SCREEN.width, SCREEN.height);
let text = detail_text_area(Rect::new(0, 0, SCREEN.width, SCREEN.height));
let bottom: String = lines[(text.bottom() - 1) as usize]
.chars()
.skip(text.x as usize)
.take(text.width as usize)
.collect();
assert!(
!bottom.trim().is_empty(),
"the last page ran into blank space:\n{}",
lines.join("\n")
);
board.scroll_detail(-40, SCREEN);
assert_eq!(board.offset, 0, "the offset went above the top");
}
/// A ticket that fits has nothing to scroll, so the keys do nothing to it.
#[test]
fn a_ticket_shorter_than_the_overlay_does_not_scroll() {
let dir = board_dir();
write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", "");
// Tall enough that the whole ticket is on screen at once.
let roomy = Size {
width: 120,
height: 60,
};
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
let before = render(&board, roomy.width, roomy.height);
board.scroll_detail(1, roomy);
assert_eq!(board.offset, 0);
assert_eq!(render(&board, roomy.width, roomy.height), before);
}
/// Up and down still move the selection with the detail view open, and the modal
/// follows, which is the reason the scroll went on pgup and pgdn in the first place.
#[test]
fn the_selection_still_moves_under_an_open_detail_view() {
let dir = board_dir();
write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "Alpha", "");
write_ticket(&dir, "backlog", "22222222-0000-4000-8000-000000000000", "Beta", "");
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
// By id rather than title: the body leaves the title to the caller that prints
// the heading, so the detail text does not carry it.
assert!(board.detail.clone().unwrap().contains("11111111"), "{:?}", board.detail);
board.select_card(1);
assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string()));
assert!(board.detail.clone().unwrap().contains("22222222"), "{:?}", board.detail);
}
/// A newly selected ticket starts at its own top, not where the last one was left.
#[test]
fn the_scroll_offset_resets_when_the_selection_moves() {
let dir = board_dir();
let long = long_section(60);
write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "Alpha", &long);
write_ticket(&dir, "backlog", "22222222-0000-4000-8000-000000000000", "Beta", &long);
write_ticket(&dir, "committed", "33333333-0000-4000-8000-000000000000", "Gamma", &long);
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
board.scroll_detail(1, SCREEN);
assert!(board.offset > 0);
board.select_card(1);
assert_eq!(board.offset, 0, "the next card opened partway down");
board.scroll_detail(1, SCREEN);
assert!(board.offset > 0);
board.select_column(1);
assert_eq!(board.offset, 0, "the next column opened partway down");
}
#[test]
fn the_scroll_offset_resets_when_the_detail_view_is_reopened() {
let dir = board_dir();
write_ticket(
&dir,
"backlog",
"11111111-0000-4000-8000-000000000000",
"First one",
&long_section(60),
);
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
board.scroll_detail(1, SCREEN);
assert!(board.offset > 0);
board.toggle_detail();
board.toggle_detail();
assert_eq!(board.offset, 0, "the ticket reopened where it was left");
}
/// An edit elsewhere in the tree must not throw the reader back to the top.
#[test]
fn a_tick_leaves_the_scroll_where_the_reader_put_it() {
let dir = board_dir();
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", &long_section(60));
let mut board = Board::new(&dir).unwrap();
board.toggle_detail();
board.scroll_detail(1, SCREEN);
let offset = board.offset;
let comments = dir.join("comments").join(uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
"**Comment**\nA late note.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
assert!(board.tick().unwrap(), "the tick saw no change");
assert_eq!(board.offset, offset);
}
/// The footer is what sent the reporter looking for their own mistake, so it has to
/// name the keys that exist and only those.
#[test]
fn the_footer_names_the_keys_that_work() {
let dir = board_dir();
write_ticket(
&dir,
"backlog",
"11111111-0000-4000-8000-000000000000",
"First one",
&long_section(60),
);
let mut board = Board::new(&dir).unwrap();
let closed = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(closed.contains("↑↓ card"), "{closed}");
assert!(closed.contains("enter detail"), "{closed}");
assert!(!closed.contains("scroll"), "a scroll offered with nothing open:\n{closed}");
board.toggle_detail();
let open = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(open.contains("pgup/pgdn scroll"), "{open}");
assert!(open.contains("select"), "{open}");
assert!(open.contains("enter close"), "{open}");
}
/// The board and the listing draw from the same palette, so a colour cannot exist
/// for one and not the other. The enum makes that a compile error; this pins the
/// mapping itself.