diff --git a/AGENTS.md b/AGENTS.md index f0363ee..ddb4f8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,6 +96,12 @@ and this file is for what someone changing worklane's own code needs. - **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 +- **Done is hidden until `d` asks for it.** Not a new opinion: `ls` already counts done in its summary and leaves it out of the listing. Done only grows, so a quarter of the width was going to the column least often read. The footer carries its count while it is hidden, which is the board's version of that summary line +- **Hiding is a change to what is drawn, never to what is read.** `reload` still scans the done directory and `digest` still watches it, so the footer count is right and revealing the column needs no rescan. Do not "optimise" that into a conditional scan +- `visible()` returns a prefix of `columns`, not a filter, which is what keeps `column` and `offsets` valid as indices into either. It is derived from where `DONE` actually sits rather than assuming the last slot, and `the_done_column_is_last` pins the assumption. A status inserted after done would otherwise hide two columns in silence +- Hiding the column under the selection moves the selection to the last drawn column and **closes an open detail view**. The alternative, refreshing the modal onto whichever ticket the selection landed on, swaps what someone is reading without saying so, which is how a person acts on the wrong ticket. Showing done again is a no-op for the selection, since a column is appended rather than inserted +- The choice is not remembered between runs. worklane has no config file and one flag is not a reason to start one; if it should persist, that is its own ticket +- **Assert a column heading against the top border row, not the whole screen.** The footer names done too, so `screen.contains("done (0)")` passes on the footer whether the column is drawn or not. Three tests went vacuous that way the moment done was hidden; `headings()` and `footer()` exist so the next one does not ### Shipping the Agent Assets - The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it diff --git a/Cargo.lock b/Cargo.lock index e6272bb..6079918 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.8.1" +version = "0.8.2" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index ff82aa4..5e30cf0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.8.1" +version = "0.8.2" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 99d8ac8..fe48776 100644 --- a/README.md +++ b/README.md @@ -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, `pgup`/`pgdn` to scroll an open ticket, `q` to quit | +| `worklane` or `worklane tui` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. 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>` | diff --git a/src/handlers.rs b/src/handlers.rs index 6af9f0b..ddad5e5 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -71,7 +71,7 @@ pub fn cmd_ls( // Show all tickets except done grouped by status for status in &statuses { - if *status == "done" { + if *status == DONE { continue; } let status_path = worklane_dir.join(status); diff --git a/src/main.rs b/src/main.rs index fcfa586..7a11e3b 100644 --- a/src/main.rs +++ b/src/main.rs @@ -161,6 +161,8 @@ fn run_tui(start: &std::path::Path) -> Result<()> { KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen), KeyCode::PageUp => board.scroll_detail(-1, screen), KeyCode::PageDown => board.scroll_detail(1, screen), + // Free of the other bindings, and the footer names it in both states. + KeyCode::Char('d') => board.toggle_done(screen), _ => {} } } diff --git a/src/tui.rs b/src/tui.rs index 32f7e40..e1d9469 100644 --- a/src/tui.rs +++ b/src/tui.rs @@ -42,6 +42,9 @@ pub struct Board { pub detail: Option, /// First visible line of the detail view, counted in wrapped lines. pub offset: u16, + /// Whether the done column is drawn. Off at startup, and not remembered between + /// runs: worklane has no config file, and one flag is not a reason to start one. + pub show_done: bool, pub should_quit: bool, worklane_dir: PathBuf, digest: u64, @@ -56,6 +59,7 @@ impl Board { offsets: Vec::new(), detail: None, offset: 0, + show_done: false, should_quit: false, worklane_dir: worklane_dir.to_path_buf(), digest: 0, @@ -109,15 +113,63 @@ impl Board { Ok(()) } + /// The columns that are drawn: all of them, or everything up to done. + /// + /// A prefix rather than a filter, which is what keeps `column` and `offsets` usable + /// as indices into either. Taken from where done actually is instead of assuming the + /// last slot, with a test pinning done as last so the two cannot drift apart. + pub fn visible(&self) -> &[Column] { + &self.columns[..self.visible_count()] + } + + fn visible_count(&self) -> usize { + if self.show_done { + return self.columns.len(); + } + + match self.columns.iter().position(|column| column.status == DONE) { + Some(index) => index, + None => self.columns.len(), + } + } + + /// Show or hide the done column. + /// + /// `ls` already holds this opinion: it counts done in its summary and leaves it out + /// of the listing. Done only grows, so a quarter of the width goes to the column + /// least often read while the three being worked get squeezed for it. + /// + /// Hiding is a change to what is drawn, never to what is read. The directory stays + /// scanned and stays in the digest, so the count in the footer is right and revealing + /// the column needs no rescan. + pub fn toggle_done(&mut self, screen: Size) { + self.show_done = !self.show_done; + + // Showing done again appends a column, so nothing below is reached and the + // selection stays exactly where it was. + if self.column < self.visible_count() { + return; + } + + // Hiding the column the selection is in moves it to the last one still drawn. + // An open detail closes with it: it is showing a ticket that is no longer on the + // board, and quietly swapping it for a different ticket is worse than closing. + self.clamp(); + self.detail = None; + self.offset = 0; + self.follow_selection(screen); + } + /// Keep the selection on a card that exists, after the board changes under it. fn clamp(&mut self) { - if self.columns.is_empty() { + let visible = self.visible_count(); + if visible == 0 { self.column = 0; self.card = 0; return; } - self.column = self.column.min(self.columns.len() - 1); + self.column = self.column.min(visible - 1); let count = self.columns[self.column].tickets.len(); self.card = match count { 0 => 0, @@ -133,11 +185,12 @@ impl Board { /// Move between columns, keeping the card index where it can land. pub fn select_column(&mut self, delta: isize, screen: Size) { - if self.columns.is_empty() { + if self.visible_count() == 0 { return; } - let last = self.columns.len() as isize - 1; + // Bounded by what is drawn, so the selection cannot walk into a hidden column. + let last = self.visible_count() as isize - 1; let next = (self.column as isize + delta).clamp(0, last); self.column = next as usize; self.clamp(); @@ -326,10 +379,12 @@ pub fn draw(frame: &mut Frame, board: &Board) { } fn draw_columns(frame: &mut Frame, board: &Board, area: Rect) { - let widths: Vec = board - .columns + // Only the drawn columns are measured, so hiding done gives its width back to the + // three that are left rather than leaving a gap where it was. + let columns = board.visible(); + let widths: Vec = columns .iter() - .map(|_| Constraint::Ratio(1, board.columns.len().max(1) as u32)) + .map(|_| Constraint::Ratio(1, columns.len().max(1) as u32)) .collect(); let areas = Layout::default() @@ -337,7 +392,7 @@ fn draw_columns(frame: &mut Frame, board: &Board, area: Rect) { .constraints(widths) .split(area); - for (index, column) in board.columns.iter().enumerate() { + for (index, column) in columns.iter().enumerate() { let focused = index == board.column; let title = format!(" {} ({}) ", column.status, column.tickets.len()); @@ -464,9 +519,16 @@ fn card_lines(ticket: &TicketItem, selected: bool) -> Vec> { } fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { + // While done is hidden its count goes here, which is the board's version of the + // summary line `ls` prints above a listing that leaves done out. + let done = match board.show_done { + true => "d hide done".to_string(), + false => format!("d show done ({})", done_count(board)), + }; + let keys = match board.detail { - Some(_) => " ←→↑↓ select pgup/pgdn scroll enter close q quit ", - None => " ←→ column ↑↓ card enter detail q quit ", + Some(_) => format!(" ←→↑↓ select pgup/pgdn scroll enter close {done} q quit "), + None => format!(" ←→ column ↑↓ card enter detail {done} q quit "), }; frame.render_widget( @@ -475,6 +537,15 @@ fn draw_footer(frame: &mut Frame, board: &Board, area: Rect) { ); } +/// How many tickets are in done, drawn or not. +fn done_count(board: &Board) -> usize { + board + .columns + .iter() + .find(|column| column.status == DONE) + .map_or(0, |column| column.tickets.len()) +} + /// Where the detail overlay sits in the frame. /// /// Inset, so the board stays visible around the edges and the overlay reads as one. @@ -596,20 +667,201 @@ mod tests { .collect() } + /// The column headings, which sit on the top border row. + /// + /// That row alone, because the footer names done as well: a whole-screen search for + /// `done (0)` passes on the footer whether the column is drawn or not, which is how + /// three of these tests came to be vacuous the moment done was hidden. + fn headings(board: &Board, width: u16, height: u16) -> String { + render(board, width, height).remove(0) + } + + fn footer(board: &Board, width: u16, height: u16) -> String { + render(board, width, height).pop().expect("no rows rendered") + } + #[test] - fn the_board_draws_the_four_statuses_as_columns() { + fn the_board_draws_the_four_statuses_as_columns_once_done_is_shown() { let dir = board_dir(); write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", ""); write_ticket(&dir, "committed", "22222222-0000-4000-8000-000000000000", "Second one", ""); - let board = Board::new(&dir).unwrap(); - let screen = render(&board, 120, 20).join("\n"); + let mut board = Board::new(&dir).unwrap(); + board.toggle_done(SCREEN); + let row = headings(&board, 120, 20); for heading in ["backlog (1)", "committed (1)", "reviewing (0)", "done (0)"] { - assert!(screen.contains(heading), "no {heading:?} in:\n{screen}"); + assert!(row.contains(heading), "no {heading:?} in:\n{row}"); } } + /// Done only grows, and it is the column least often read. `ls` already leaves it + /// out of its listing while counting it in the summary; this is the same opinion. + #[test] + fn the_board_opens_with_the_done_column_hidden() { + let dir = board_dir(); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", ""); + write_ticket(&dir, "done", "44444444-0000-4000-8000-000000000000", "Finished one", ""); + + let board = Board::new(&dir).unwrap(); + assert!(!board.show_done, "done was drawn at startup"); + + let row = headings(&board, 120, 20); + for heading in ["backlog (1)", "committed (0)", "reviewing (0)"] { + assert!(row.contains(heading), "no {heading:?} in:\n{row}"); + } + assert!(!row.contains("done"), "done is still a column:\n{row}"); + + // Hidden, not unread: the count is right and revealing it needs no rescan. + assert_eq!(board.columns.len(), 4); + assert_eq!(board.visible().len(), 3); + assert_eq!(done_count(&board), 1); + assert!( + !render(&board, 120, 20).join("\n").contains("Finished one"), + "a hidden done ticket was drawn" + ); + } + + /// The three that are left take the width done was using, rather than leaving a gap. + #[test] + fn the_visible_columns_share_the_full_width() { + let dir = board_dir(); + let mut board = Board::new(&dir).unwrap(); + + let hidden = headings(&board, 120, 20); + assert_eq!(hidden.matches('┌').count(), 3, "{hidden}"); + assert!(hidden.ends_with('┐'), "the columns stop short of the edge:\n{hidden}"); + + board.toggle_done(SCREEN); + let shown = headings(&board, 120, 20); + assert_eq!(shown.matches('┌').count(), 4, "{shown}"); + assert!(shown.ends_with('┐'), "{shown}"); + } + + /// Hiding is a prefix of the columns, which only holds while done is last. The + /// board leans on that, so the assumption is pinned rather than assumed. + #[test] + fn the_done_column_is_last() { + assert_eq!(status_dirs().last(), Some(&DONE)); + } + + #[test] + fn the_footer_names_the_key_and_carries_the_count_while_done_is_hidden() { + let dir = board_dir(); + for (n, title) in [("44444444", "One"), ("55555555", "Two")] { + write_ticket(&dir, "done", &format!("{n}-0000-4000-8000-000000000000"), title, ""); + } + + let mut board = Board::new(&dir).unwrap(); + let hidden = footer(&board, 120, 20); + assert!(hidden.contains("d show done (2)"), "{hidden}"); + + board.toggle_done(SCREEN); + let shown = footer(&board, 120, 20); + assert!(shown.contains("d hide done"), "{shown}"); + // With the column drawn, its own heading carries the count. + assert!(!shown.contains("(2)"), "the count is printed twice:\n{shown}"); + } + + /// The modal footer names it too, since the key works with a ticket open. + #[test] + fn the_detail_footer_also_names_the_done_key() { + let dir = board_dir(); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", ""); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + + let row = footer(&board, 120, 20); + assert!(row.contains("d show done (0)"), "{row}"); + assert!(row.contains("pgup/pgdn scroll"), "{row}"); + } + + /// Hiding the column under the selection has to move it, or it points at nothing. + #[test] + fn hiding_done_under_the_selection_moves_it_to_the_last_visible_column() { + let dir = board_dir(); + write_ticket(&dir, "reviewing", "33333333-0000-4000-8000-000000000000", "Ready", ""); + write_ticket(&dir, "done", "44444444-0000-4000-8000-000000000000", "Finished", ""); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_done(SCREEN); + board.select_column(3, SCREEN); + assert_eq!(board.selected().map(|t| t.title.clone()), Some("Finished".to_string())); + + board.toggle_done(SCREEN); + assert_eq!(board.column, 2, "the selection stayed on a column that is gone"); + assert_eq!(board.selected().map(|t| t.title.clone()), Some("Ready".to_string())); + } + + /// And an open detail of a done ticket goes with it: showing a ticket that is no + /// longer on the board is worse than closing, and swapping it for a different + /// ticket without saying so is worse than both. + #[test] + fn hiding_done_closes_a_detail_view_of_a_done_ticket() { + let dir = board_dir(); + write_ticket(&dir, "reviewing", "33333333-0000-4000-8000-000000000000", "Ready", ""); + write_ticket(&dir, "done", "44444444-0000-4000-8000-000000000000", "Finished", ""); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_done(SCREEN); + board.select_column(3, SCREEN); + board.toggle_detail(); + assert!(board.detail.is_some()); + + board.toggle_done(SCREEN); + assert!(board.detail.is_none(), "{:?}", board.detail); + } + + /// A ticket being read in a column that is not going anywhere stays open. + #[test] + fn hiding_done_leaves_a_detail_view_of_another_ticket_open() { + let dir = board_dir(); + write_ticket(&dir, "backlog", "11111111-0000-4000-8000-000000000000", "First one", ""); + + let mut board = Board::new(&dir).unwrap(); + board.toggle_detail(); + board.toggle_done(SCREEN); + board.toggle_done(SCREEN); + + assert!(board.detail.is_some(), "an unrelated detail view was closed"); + } + + /// Done is appended rather than inserted, so showing it moves nothing. + #[test] + fn showing_done_again_leaves_the_selection_where_it_was() { + let dir = board_dir(); + write_ticket(&dir, "committed", "22222222-0000-4000-8000-000000000000", "Alpha", ""); + write_ticket(&dir, "committed", "33333333-0000-4000-8000-000000000000", "Beta", ""); + write_ticket(&dir, "done", "44444444-0000-4000-8000-000000000000", "Finished", ""); + + let mut board = Board::new(&dir).unwrap(); + board.select_column(1, SCREEN); + board.select_card(1, SCREEN); + let (column, card) = (board.column, board.card); + + board.toggle_done(SCREEN); + assert_eq!((board.column, board.card), (column, card)); + assert_eq!(board.selected().map(|t| t.title.clone()), Some("Beta".to_string())); + } + + /// The selection cannot walk into a column that is not drawn. + #[test] + fn the_selection_stops_at_the_last_visible_column() { + let dir = board_dir(); + write_ticket(&dir, "done", "44444444-0000-4000-8000-000000000000", "Finished", ""); + + let mut board = Board::new(&dir).unwrap(); + board.select_column(9, SCREEN); + assert_eq!(board.column, 2); + assert!(board.selected().is_none(), "the selection reached the done column"); + + board.toggle_done(SCREEN); + board.select_column(9, SCREEN); + assert_eq!(board.column, 3); + assert_eq!(board.selected().map(|t| t.title.clone()), Some("Finished".to_string())); + } + /// The card has to carry enough to identify the ticket without opening it. #[test] fn a_card_shows_the_short_id_title_owner_and_due() { @@ -630,12 +882,13 @@ mod tests { fn an_empty_status_renders_as_an_empty_column() { let dir = board_dir(); - let board = Board::new(&dir).unwrap(); + let mut board = Board::new(&dir).unwrap(); assert_eq!(board.columns.len(), 4); - let screen = render(&board, 120, 20).join("\n"); + board.toggle_done(SCREEN); + let row = headings(&board, 120, 20); for status in status_dirs() { - assert!(screen.contains(&format!("{status} (0)")), "{screen}"); + assert!(row.contains(&format!("{status} (0)")), "{row}"); } } @@ -643,11 +896,13 @@ mod tests { #[test] fn a_missing_status_directory_is_still_a_column() { let dir = board_dir(); - std::fs::remove_dir_all(dir.join("done")).unwrap(); + std::fs::remove_dir_all(dir.join(DONE)).unwrap(); - let board = Board::new(&dir).unwrap(); + let mut board = Board::new(&dir).unwrap(); assert_eq!(board.columns.len(), 4); - assert!(render(&board, 120, 20).join("\n").contains("done (0)")); + + board.toggle_done(SCREEN); + assert!(headings(&board, 120, 20).contains("done (0)")); } #[test] @@ -1244,4 +1499,5 @@ mod tests { assert_ne!(tui, ratatui::style::Color::Reset, "level {level} has no colour"); } } + } diff --git a/src/util.rs b/src/util.rs index 5f9d312..e75afa1 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1095,9 +1095,18 @@ pub fn trim_blank_ends(values: &[String]) -> &[String] { } pub fn status_dirs() -> Vec<&'static str> { - vec!["backlog", "committed", "reviewing", "done"] + vec!["backlog", "committed", "reviewing", DONE] } +/// The end of the flow, and the one status both views treat differently: `ls` counts it +/// in the summary and leaves it out of the listing, and the board hides its column until +/// asked. Named because that rule now has two readers. +/// +/// It is deliberately last in `status_dirs()`. The board leans on that: hiding done drops +/// the final column, so the other three keep their indices and the selection only has to +/// be handled when it is sitting on done itself. +pub const DONE: &str = "done"; + /// Lowest and highest level a ticket can carry. 1 is the most urgent, which is /// what the `p1` to `p3` tags this replaced already meant. pub const PRIORITY_RANGE: std::ops::RangeInclusive = 1..=5;