Compare commits

...
6 Commits
Author SHA1 Message Date
Ansho ReiandClaude Fable 5 c03f47c52d (f774a33) Record a campaign move in the history log, and bump to 0.30.0
assign was the only field writer without an entry: a ticket could leave one
campaign for another with nothing recording it. Kind gains Campaign, assign
gains the --actor flag the other four writers carry, and the entry is written
after the save and behind the no-change return, the rule every writer follows.

The entry records Campaign::name, the codename or failing that the title,
settled when the entry is written so a rename cannot change what an old entry
means. The uuid the field holds says nothing in a log line, and a before-uuid
the board no longer has reads _missing_, the way the Campaign field itself
renders a dangling one.

campaign is the longest mechanical label, so LABEL_WIDTH widens from 6 to 8
and every mechanical row moves two columns right, a deliberate output change
that makes this a minor alongside the new flag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 15:49:50 +02:00
Ansho ReiandClaude Fable 5 9d17f55860 (f3e099e) Colour the history block in the detail overlay, and bump to 0.29.1
The board appended the block as a pre-rendered string with colour off, the
last flat piece of a body e4d0bb7 had fully styled. history_cells lays the
block out once: format_history is those cells painted for the CLI, and
detail_of pushes the same ones as a Cells part, so the overlay styles them
and no escape can enter. The CLI's output is pinned byte for byte, and the
overlay test pairs the presence of the colours with the absence of escapes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 14:49:24 +02:00
Ansho ReiandClaude Opus 5 f454d212a4 (d4ce964) Record status, owner and tag changes in a history log, and bump to 0.29.0
The comments directory was already an append-only log with one event
kind. It is now .worklane/history/<uuid>/, with the kind in the entry
and in the filename after the stamp, so a ticket says how it got where
it is and not only what was said about it.

mv, chown and set --tags each write an entry after their own save and
behind their own no-change return, so a refused or no-op edit records
nothing. --actor is on all four writers now. An old comments directory
is adopted on first access and a file with no marker reads as the
comment it is, so nothing is migrated or rewritten.

The log moves to src/history.rs, out of util.rs and handlers.rs, and
the card's counter counts comments only: a ticket that has moved three
times has not been talked about.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 13:19:09 +02:00
Ansho ReiandClaude Opus 5 a1bdb5df49 (87862df) Attribute an entry to WORKLANE_ACTOR, not to the git user, and bump to 0.28.0
Every comment the CLI wrote was attributed to the git user, so a board
several agents write to read as a list of things one human had done.
resolve_actor is now the single source: flag, then WORKLANE_ACTOR, then
get_git_user(), then unknown.

comment --owner is renamed to --actor with no alias, since it names the
writer of the entry and not the ticket's assignee, which is chown's.
add --owner and campaign add --owner still default to the git user.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 12:34:51 +02:00
Ansho Rei c2ee165108 (e4d0bb7) Colour the whole detail overlay body, not just its relations, and bump to 0.27.3
The block was the only coloured part because it arrived as rows while
everything else arrived as a painted string, and the board had to ask for
the unpainted one: an escape in a ratatui paragraph is drawn as literal
bytes.

content_parts now paints nothing. BodyPart::Text becomes
BodyPart::Cells, so content_trim is the cells through paint_cells and the
board is the same cells through span_from. push_heading, ordered_cells,
inline_cells, metadata_cells, metadata_value_cells and tag_cells replace
the painters they were. Resolved.campaign is cells too, which made
reference_cell dead at its last caller.

The colored flag still reaches content_parts and no longer means paint.
It says whether this renderer can carry a colour at all, and one thing
turns on it: **bold** gives its markers up to the colour that replaces
them, so a renderer with none has to keep them.

Color::Magenta.ansi() is \x1b[1;35m, so span_from adds the bold modifier
on the board's side, since From<Color> carries only the colour and the
same cell must not be painted two ways.

show's output is pinned byte for byte against what it printed before,
both by a fixture holding one of every painted run and by diffing the
old binary against the new one over every ticket and campaign on this
board, coloured and piped.
2026-08-24 11:57:25 +02:00
Ansho Rei 407cb14fe6 (e6e3a1b) Guard the README command table against a missing row
The campaign and assign rows landed with 528566d. What was left was the
checking, done here against the built binary rather than against the
ticket that added them.

The campaign ls row was incomplete: the listing also prints the derived
state, [open] until every member is done and [done] after, and reads
"no members" with no state for a campaign nothing has been filed
against, which is neither. Corrected.

every_subcommand_has_a_row_in_the_readme_command_table walks clap's own
subcommands, one level of nesting included, against the table's rows.
Two commands hid behind an otherwise complete table for two minor
versions because the only thing walking it was somebody remembering to.
The tag subcommands are named in a PENDING list rather than skipped,
since f7dd1a1 rewrites that row.
2026-08-24 11:28:32 +02:00
19 changed files with 2316 additions and 482 deletions
+52 -18
View File
@@ -7,6 +7,7 @@
- `src/handlers.rs` - one `cmd_*` per subcommand
- `src/util.rs` - the ticket format, resolution, rendering and the palette
- `src/campaign.rs` - the campaign file format, its resolution, its index and its members
- `src/history.rs` - the history log: the path, the kinds, the reader, the writer, the card's counter and the block `show` and the board both render
- `src/tui.rs` - board state, the change digest, and the ratatui draw
- `src/clipboard.rs` - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
- `src/install.rs` - the embedded agent assets and the compare-and-refuse install
@@ -16,20 +17,21 @@
- `assets/ADMIN.md` - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against `PLAN.md` in both directions: this one decides the vocabulary, that one applies it
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `history.rs` and `tui.rs`
- Ticket files stored as `.md` in `.worklane/<status>/` directories
- History entries stored as `.md` in `.worklane/history/<ticket_uuid>/`, one file per entry, beside the status directories for the reason campaigns are
- Campaign files stored as `.md` in `.worklane/campaigns/`, which is beside the status directories and deliberately not in `status_dirs()`
## Ticket File Format
- Filenames: `<uuid_v4>_<slug>.md`
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- Format: `**Field Name**: value`
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
- History entries stored in `.worklane/history/<ticket_uuid>/<stamp>_<kind>.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`, `**Campaign**`), then the body, then `**Author**` and `**Time**`. See The History Log
## Status Workflow
`backlog` → `committed` → `reviewing` → `done`
@@ -175,7 +177,7 @@ and this file is for what someone changing worklane's own code needs.
- **A campaign's state is derived, never stored.** Open until every member is done, computed by `Standing` from the members. A `Status` field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no `campaign mv` and no forward-only ruleset beside `mv`'s
- **A campaign with no members is neither open nor done.** `Standing::state()` returns `None` there, and both callers print `no members`. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
- **Membership is one field on the member**, `Campaign` in the ticket Metadata, written only by `assign`. The member list is deliberately *not* on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So `add` has no `--campaign` and `set` has no `--campaign`, the same rule as Owner and Status
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cell` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cells` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
- **`add` does not write the field.** Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of `add` means one path that is always exercised rather than two. Same reasoning as the Relations section
- `set_or_insert_metadata_field()` is the upsert, and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no `## Metadata` heading is an **error, not an insertion**: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
- **The four tiers are `resolve_in()`, shared by tickets and campaigns.** A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. `Found.dir` is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
@@ -229,7 +231,7 @@ and this file is for what someone changing worklane's own code needs.
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on saying `q quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
- **The overlay names its ticket on the border, not at the head of the paragraph.** `Board::detail` is a `Detail` carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: `content_trim` drops the `# ` heading on purpose, since `cmd_show` prints it, and anything in the paragraph scrolls away
- `detail_title` cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
- 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
- The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_history_with` take the colour decision for the CLI's side of the same layouts
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
@@ -237,12 +239,12 @@ and this file is for what someone changing worklane's own code needs.
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
- **`corner_line`'s right side is a group, single-spaced, and it gives up its items from the front.** The item nearest the edge is what the corner is *about*; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an `Option`. The spacing between the items lives in `corner_line` with the gap arithmetic rather than in a caller, for the reason `column_areas` is shared: geometry reproduced by hand drifts from the draw. `due_span` returns a `Span` and not an `Option<Span>` now, since the `Option` only ever existed to satisfy the old signature and the function cannot fail
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The comments live outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_comments` applies, and no body is read, because a count needs none of them. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the comments of another. `comments_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The history lives outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_history` applies, and no body is read, because a count needs none of them. **It counts comments and not entries**, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. `history_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
- **The count is cyan and the mark is `COMMENT_MARK`, U+275E, a Dingbat.** It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where `spans_width` counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the comments directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the history directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cells` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
@@ -280,7 +282,7 @@ and this file is for what someone changing worklane's own code needs.
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
- **`digest` watches the campaigns directory** as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
- `tags` is a field on `TicketItem`, filled in `collect_ticket_items` through `parse_tags`, for the reason the criteria count is. `parse_tags` splits the comma-separated field into whole trimmed values, so a caller asking for `bug` is not answered by `bugfix`, and reads absent, `_None_` and empty as the same answer
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
@@ -328,7 +330,7 @@ and this file is for what someone changing worklane's own code needs.
### The Relations Block
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
- **`Cell` is the unit both renderers take**: a run of text and the colour it is drawn in, `None` for the default foreground. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
- **`reference_cells` is the one spelling of a cross reference.** The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was a `reference_cell` beside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone
- **A row carries two marks, kind then status**: what sort of edge this is, then how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
- The status went through one bad shape first. It was a rising bar, `▁▄▆█`, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
- **Both directions of a kind carry one mark.** `blocked by` and `blocks` are the same edge read from two ends, and the label is what says which end you are on. `both_directions_of_a_kind_carry_one_mark` pins it
@@ -340,11 +342,15 @@ and this file is for what someone changing worklane's own code needs.
- **Committed and reviewing are told apart by colour alone**, both being `◐`, so a pipe cannot tell them apart: `should_use_colors` is false and both read as under way. Accepted, because `●` and `○` are the two answers usually wanted and `show` on the target settles the rest, and `assets/SKILL.md` says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
- `RelationTarget` carries the title and the status in one `Option`, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
- **`show` and the board carry the same mark**, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
- **`Resolved.relations` is rows, not a rendered block.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
- **`Resolved.relations` is rows, not a rendered block, and `Resolved.campaign` is cells for the same reason.** An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing in `Resolved` can arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, since `content_parts` paints nothing at all
- **`BodyPart` splits the body rather than building it twice.** It is `Cells` or `Relations`: everything outside the block is laid out once, by `content_parts`, and `content_trim` is that run through `paint_cells` while the board is the same cells run through `span_from`. `Body` is the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in places
- **`Detail.body` is a `Text`, and it is the only thing measured.** `last_offset` and the `Paragraph` both take it, so the clamp cannot wrap the body differently from the draw. `Detail::plain()` flattens it for the suite and is `#[cfg(test)]`: a second representation carried alongside the spans is a second thing to disagree
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end. It now splits **per cell** rather than per part, since a `Cells` part holds many runs and a newline can fall inside any of them
- **The whole overlay body is coloured now, and `content_parts` paints nothing.** The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the same `Cell` treatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout that `show` paints and the board styles. Do not reintroduce a `paint` call in `content_parts`: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes
- **`colored` still reaches `content_parts`, and it no longer means paint.** It says whether *this* renderer can carry a colour at all, and one thing turns on it: `**bold**` gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passes `true`, `content_trim` passes the CLI's decision, and a piped `show` still reads its markers. Nothing else in the body consults it
- **Magenta means bold, and `span_from` is where the board learns that.** `Color::Magenta.ansi()` is `\x1b[1;35m`, so the CLI draws every bold run bold as well as magenta, and `From<Color>` can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent
- **The conversion is pinned from both ends.** `show_prints_the_same_body_it_printed_before_the_cells_conversion` holds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite. `the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it` is the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence
- **The history block arrives as cells too, so nothing in the overlay is flat.** `history_cells` lays the block out once; `format_history` is those cells through `paint_cells` and the board pushes the same ones as a `Cells` part after the body, since the log lives outside the ticket file and `content_parts` never sees it. Pinned from both ends the way the body is: `show_prints_the_same_history_it_printed_before_the_cells_conversion` holds the CLI's output byte for byte, and `the_history_block_is_styled_in_the_overlay_and_no_escape_reached_it` pairs the presence with the absence (f3e099e, closing the gap e4d0bb7 left)
### Finding the Board
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
@@ -367,6 +373,32 @@ and this file is for what someone changing worklane's own code needs.
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `frame_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
- `digest_of` hashes each board's `digest` into one value, so a change in any of them redraws. Do not watch only the first
### Who Wrote an Entry
- **Identity is supplied, not detected.** Every option that needs no cooperation fails: a harness variable such as `CLAUDECODE` names the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor is `WORKLANE_ACTOR`, set once per session, with `--actor` as the per-call override
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** `resolve_actor` is the only caller of `get_git_user` for an entry's author, and every entry the CLI writes goes through it. The two halves are separate pure functions, `session_actor` and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
- **The session half is cached in a `OnceLock`, the way `should_use_colors` is:** neither the variable nor the git user can change mid-run, and the fallback costs a `git config` subprocess. `session_actor` takes the git user as a closure so that subprocess is not run when the variable already answered
- An **empty `WORKLANE_ACTOR` counts as unset**, the convention `colors_wanted` follows for `NO_COLOR`, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one
- **The actor is free text, checked against nothing**, like the `chown` user: there is no registry of actors, and the same reason `ls --tag` refuses to validate a tag
- **It was `comment --owner`, renamed with no alias.** Owner is the ticket's assignee and has one writer, `chown`; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splitting `set` and `chown` avoided. `the_owner_flag_is_gone` pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
- **`add --owner` and `campaign add --owner` still default to the git user, deliberately.** Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported
- **An entry does not record whether the call had a terminal.** It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
- **Set it in the agent's configuration, not per call.** `env` in `~/.claude/settings.json` reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no `env` block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around `opencode`. Both are documented in `assets/SKILL.md` rather than assumed
### The History Log
- **The log is the comments directory with the kind named in it.** It was already an append-only log with one event kind: one file per entry under `.worklane/history/<uuid>/`, stamped to the microsecond and written with `create_new`. Adding `status`, `owner` and `tags` beside `comment` needed no new mechanism, which is why there is no separate journal file and no database
- **What is not logged, deliberately:** ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
- **`--clear` is logged, since it is the same field going somewhere.** `chown --clear` and `set --clear tags` write an entry whose after-value is the sentinel the ticket now holds, `_Not set_` or `_None_`. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does
- **The kind is read from the file and only counted from the filename.** `parse_entry` matches the leading marker; `kind_from_stem` splits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader
- **A file with no marker is a comment**, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command: `entry_content(Kind::Comment, ..)` is byte for byte what `cmd_comment` wrote before this module, so nothing is rewritten and either version can read the other's board
- **The old directory is adopted, not migrated.** `adopt_comments` renames `comments` to `history` on the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. **A board holding both is refused**, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it
- **An entry is written after the edit it describes, never before.** A refused move, a refused chown and a failed save log nothing, which is what `a_refused_move_writes_nothing` and `a_failed_edit_writes_nothing` pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it
- **A no-op edit writes nothing either, and `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them
- **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it
- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `campaign` being the longest of the four, so the bodies line up under each other
- **A campaign entry records `Campaign::name`, the codename or failing that the title, never the uuid the field holds.** Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. A `before` uuid the board no longer has reads `_missing_`, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from `_Not set_` (f774a33)
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
### 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
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
@@ -394,11 +426,12 @@ and this file is for what someone changing worklane's own code needs.
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
### Color and Output
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
- **`color_text()` is for the CLI's own printing only. Anything reachable from `content_trim` takes the decision as an argument and calls `paint()`**, because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. `nothing_the_body_renders_asks_the_terminal_for_the_colour_decision` scans this file and fails on a new caller; the allowlist is `ambiguous`, which builds a failed-search message for stderr
- A function that takes an `enabled` flag must use it all the way down. `colorize_inline` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
- A function that takes an `enabled` flag must use it all the way down. The inline pass honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag: `ordered_cells` and `metadata_value_cells` return the colour rather than a decision about it
- **A test that asserts an absence has to be paired with one that asserts the presence.** The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so `should_use_colors()` was false and the leaking branch was never taken. The pair is now `content_trim(.., false)` has no escape and `content_trim(.., true)` still colours, which pins the flag as the only thing that decides
- **The palette is the `Color` enum, not a string.** `Color::ansi()` gives the CLI its SGR sequence and `From<Color> for ratatui::style::Color` gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how `magenta` came to be undefined
- Reset color with `\x1b[0m` after colored text
@@ -427,9 +460,10 @@ and this file is for what someone changing worklane's own code needs.
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
### Code Organization
- Colorization functions (`colorize_ordered`, `colorize_inline`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
- **`colorize_inline` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- **`history.rs` owns the log end to end**: the path, the kinds, the parse, the write, the count and the render. It came out of `util.rs` and `handlers.rs`, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way `campaign.rs` and `tag.rs` answer their own questions
- The body's painters return cells, not strings: `ordered_cells`, `inline_cells`, `metadata_cells`, `metadata_value_cells`, `tag_cells` and `push_heading`. `content_trim_colored` is the CLI entry point and `paint_cells` is the only thing that writes an escape. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
- **`inline_cells` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
- `show` renders the Metadata section as a two column table via `metadata_cells`, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
- `resolve_ticket()` scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.27.2"
version = "0.30.0"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.27.2"
version = "0.30.0"
edition = "2024"
[dependencies]
+14 -6
View File
@@ -9,19 +9,19 @@ Worklane is a local Kanban flow for agentic software development.
| `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. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f` |
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to |
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion |
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
@@ -29,6 +29,14 @@ Worklane is a local Kanban flow for agentic software development.
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
## Environment
| Variable | Effect |
|----------|--------|
| `WORKLANE_ACTOR` | Who every entry the CLI writes is attributed to: a comment, and the `status`, `owner` and `tags` entries `mv`, `chown` and `set --tags` record. Set it once, in the environment an agent runs in, and every call it makes is attributed to it instead of to the git user of whoever's machine it is on. `--actor` overrides it per call, an empty value counts as unset, and with neither supplied the author is the git user and then `unknown`. Free text, checked against nothing |
| `NO_COLOR` | Set and non-empty turns colour off, whatever the value, per no-color.org. Colour is also off when output is not a terminal, and when `TERM` is `dumb` or empty |
| `XDG_CONFIG_HOME` | Where `install-tool` looks for opencode's config root, `$XDG_CONFIG_HOME/opencode`, defaulting to `~/.config`. `install-skill` does not follow it: `~/.claude` is not an XDG path |
## Completions
```sh
+66 -7
View File
@@ -6,10 +6,10 @@ description: Manage tickets on a local worklane kanban board with the `worklane`
# worklane
A kanban board as files. Every ticket is one markdown file in `.worklane/<status>/`,
named `<uuid>_<slug>.md`, and comments live in `.worklane/comments/<uuid>/`. The CLI is
the only thing that writes there: do not hand-edit or hand-place a file, because the
filename, the `Status` field and the directory have to agree and the commands are what
keep them agreeing.
named `<uuid>_<slug>.md`, and its history lives in `.worklane/history/<uuid>/`, one file
per entry. The CLI is the only thing that writes there: do not hand-edit or hand-place a
file, because the filename, the `Status` field and the directory have to agree and the
commands are what keep them agreeing.
Commands walk up from the working directory to find the nearest `.worklane`, so **run
`worklane` inside the repo the ticket belongs to**. Which directory you run it in is
@@ -48,7 +48,7 @@ worklane ls # every status, counts then tickets
worklane ls backlog # one status
worklane ls --priority 1 # only the most urgent
worklane ls --tag bug # only the tickets carrying that tag
worklane show 1b78a24 # one ticket, body and comments
worklane show 1b78a24 # one ticket, body and history
```
`ls` prints a seven-character id per ticket. That is what you address it by.
@@ -270,6 +270,62 @@ existing ticket will have been written from a different angle.
- Related but not the same: file it, and record it with `relate <new> --relates-to <old>`
rather than only mentioning the id in prose.
## What the board records about your work
`show` ends with a HISTORY block: every comment on the ticket and every change to its
status, owner, tags or campaign, oldest first, each naming who made it. You do not write
these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call
that changes nothing records nothing. A campaign move is recorded by codename, or by
title for a campaign that has none, not by the uuid the field holds.
```
HISTORY
────────────────────
status backlog → committed claude (2026-08-24 12:45:00)
From claude (2026-08-24 13:10:22)
The offset was never passed to the widget.
owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04)
campaign _Not set_ → v1 claude (2026-08-24 13:12:30)
```
Nothing else is logged: ticking a criterion, and editing the title, description, plan,
priority or due date, leave no entry. **When one of those matters, say so in a comment.**
An implementation plan rewritten because the first one was wrong is worth a sentence; the
edit itself is not recorded and nobody can reconstruct why from the file.
Read the block before picking a ticket up: it says whether somebody has already had it in
`committed` and sent it back, which the current status alone does not.
## Who your entries are attributed to
Every comment carries an author, and by default that is the git user of the machine you
are running on, which is the human whose checkout it is and not you. Set
`WORKLANE_ACTOR` in your own environment and it becomes the author of every entry you
write, so a board several agents write to says which of them said what:
```
WORKLANE_ACTOR=claude worklane comment 1b78a24 "The offset was never passed to the widget."
```
Set it once where your session's environment is configured, not on each call: `env` in
`~/.claude/settings.json` for Claude Code, and the environment opencode is started with
for opencode, since it passes its own environment to the tools it runs. `--actor`
overrides it for one call and is spelled the same on every command that writes an entry,
`comment`, `mv`, `chown`, `set` and `assign`. An empty value counts as unset and falls
back to the
git user, and with nothing at all the author is `unknown`. It is free text, checked
against nothing: name yourself something a person reading the board will recognise.
On `chown`, `--actor` is not the user argument: `worklane chown alice 1b78a24` makes alice
the ticket's owner, and `--actor` says who made that change.
If the variable is not set and you cannot set it, pass `--actor` rather than letting the
comment claim to be the user's.
## Shell completions
```
@@ -300,8 +356,8 @@ the candidates and exits 1 rather than guessing.
`--print is supported` is stored, not parsed as a flag. The cost is that a genuinely
mistyped flag there lands as content instead of failing, so read back what you wrote
with `worklane show`.
- `--due`, `--priority`, `--tags`, `--owner` and `--status` do *not* accept one, so a
mistyped flag on those is a usage error and nothing is written.
- `--due`, `--priority`, `--tags`, `--owner`, `--actor` and `--status` do *not* accept one,
so a mistyped flag on those is a usage error and nothing is written.
- A ticket argument that starts with a hyphen needs the flags first and a separator:
`worklane mv --status committed -- -leading-title`.
- A comment body of exactly `--` needs its own separator:
@@ -309,4 +365,7 @@ the candidates and exits 1 rather than guessing.
- An empty value for a scalar is a usage error, not a way to clear the field: use
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
the section either, and an all-blank one is refused with the `--clear` for it named.
- **`comment` has no `--owner`.** Owner is the ticket's assignee, which `chown` writes;
the author of a comment is `--actor` or `WORKLANE_ACTOR`. The old spelling is a usage
error, not an alias.
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
+26 -6
View File
@@ -187,7 +187,7 @@ export const ls = tool({
export const show = tool({
description:
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and comments.",
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and the history: every comment on it and every change to its status, owner or tags.",
args: {
id: tool.schema
.string()
@@ -219,6 +219,10 @@ export const mv = tool({
.boolean()
.describe("Force move (allows non-sequential moves like done -> backlog). Use with caution.")
.optional(),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
@@ -229,6 +233,7 @@ export const mv = tool({
}
const cmd: string[] = ["mv", args.ticket, "--status", args.status];
if (args.force) cmd.push("--force");
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
@@ -247,9 +252,9 @@ export const comment = tool({
body: tool.schema
.string()
.describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."),
owner: tool.schema
actor: tool.schema
.string()
.describe("Comment author. If omitted, defaults to the git user.")
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
@@ -261,7 +266,7 @@ export const comment = tool({
}
const cmd: string[] = ["comment", args.ticket, args.body];
if (args.owner) cmd.push("--owner", args.owner);
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
@@ -306,6 +311,10 @@ export const set = tool({
.string()
.describe("New priority level, 1 (most urgent) to 5 (least)")
.optional(),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
@@ -330,8 +339,12 @@ export const set = tool({
if (args.tags) cmd.push("--tags", args.tags);
if (args.due) cmd.push("--due", args.due);
if (args.priority) cmd.push("--priority", String(args.priority));
// Last, and not counted as a field: the length check below is what refuses a call
// that names nothing to change, and an actor alone changes nothing.
const fields = cmd.length;
if (args.actor) cmd.push("--actor", args.actor);
if (cmd.length === 2) {
if (fields === 2) {
return "Error setting fields: give at least one field to change";
}
@@ -405,6 +418,10 @@ export const chown = tool({
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
actor: tool.schema
.string()
.describe("Who the entry is attributed to, which on this command is not the same as user: user becomes the ticket's owner, actor is who made the change. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\".")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.user) {
@@ -414,8 +431,11 @@ export const chown = tool({
return "Error changing owner: ticket is required";
}
const cmd: string[] = ["chown", args.user, args.ticket];
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(["chown", args.user, args.ticket], context);
return await run(cmd, context);
} catch (err: any) {
return `Error changing owner: ${err.message}`;
}
+20 -5
View File
@@ -50,6 +50,21 @@ pub struct Campaign {
pub content: String,
}
impl Campaign {
/// The name a reader knows the campaign by: the codename, or the title for a
/// campaign filed without one.
///
/// What the history log records for a campaign move. The field holds a uuid, which
/// says nothing in a log line, and resolving at read time would let an entry change
/// meaning when a campaign is renamed, so the name is settled when the entry is
/// written. The codename over the title because it is the word the board and the
/// command line already use for the campaign, and a log row holds two of these
/// around an arrow.
pub fn name(&self) -> &str {
self.codename.as_deref().unwrap_or(&self.title)
}
}
/// The campaigns directory as [`resolve_in`] takes it.
///
/// The name is empty because a campaign has no status: it is what makes the ambiguity
@@ -173,22 +188,22 @@ impl CampaignIndex {
/// target does, rather than as the bare value the file stores: the value is a full
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
/// gone.
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
pub fn campaign_cells(content: &str, index: &CampaignIndex) -> Vec<Cell> {
let Some(uuid) = parse_campaign(content) else {
return String::new();
return Vec::new();
};
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
reference_cells(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()))
}
/// The parts [`content_trim`] cannot render from the ticket file alone.
///
/// Both halves read the tree beside the ticket, so they are gathered in one place
/// rather than at each call site.
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
pub fn resolved_for(content: &str, worklane_dir: &Path) -> Result<Resolved> {
Ok(Resolved {
relations: relations_for(content, worklane_dir)?,
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
campaign: campaign_cells(content, &CampaignIndex::load(worklane_dir)?),
})
}
+91 -3
View File
@@ -180,6 +180,12 @@ fn annotation_line(raw: &str) -> Result<String, String> {
}
}
/// What `--actor` says on every command that writes a history entry.
///
/// One string, so the five spell it the same: a flag documented differently on each
/// command reads as five flags.
const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing";
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
@@ -221,6 +227,9 @@ pub enum Command {
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
force: bool,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
/// Replace fields on an existing ticket
@@ -267,9 +276,10 @@ pub enum Command {
#[arg(allow_hyphen_values = PROSE)]
body: String,
/// Owner
#[arg(short, long)]
owner: Option<String>,
/// Named after the writer of the entry, not after the ticket's assignee, which
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
/// Group tickets that have to be finished together
@@ -292,6 +302,9 @@ pub enum Command {
/// Ticket UUID or title
ticket: String,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
},
/// The tag vocabulary: what the board carries, and what each tag means
@@ -728,6 +741,11 @@ pub struct SetArgs {
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
/// Only reaches the entry `--tags` writes, since that is the one field of this
/// command's that is logged
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
}
impl SetArgs {
@@ -773,6 +791,11 @@ pub struct ChownArgs {
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
/// Not the same as `user`, which is the ticket's new assignee: this is who made the
/// change. Both are on this command because it writes both.
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
}
impl ChownArgs {
@@ -881,3 +904,68 @@ pub struct CheckArgs {
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
pub criteria: Vec<String>,
}
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;
/// The command names as the README table would have to spell them: `campaign add`
/// for a nested one, the bare name for a top level one. `help` is clap's own and
/// documents nothing.
fn documented_names() -> Vec<String> {
let cli = Cli::command();
let mut names = Vec::new();
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
names.push(sub.get_name().to_string());
for nested in sub.get_subcommands() {
if nested.get_name() == "help" {
continue;
}
names.push(format!("{} {}", sub.get_name(), nested.get_name()));
}
}
names
}
/// Every subcommand has a row in the README's command table.
///
/// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and
/// the `--campaign` flag went with them, because the only thing walking the table
/// was somebody remembering to. This is what walks it. A command whose row is
/// missing is a command a reader of the README cannot discover at all, which is a
/// worse failure than a row that is merely out of date.
#[test]
fn every_subcommand_has_a_row_in_the_readme_command_table() {
// The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row
// once the vocabulary work above it has landed. Listed rather than skipped, so
// emptying this is part of closing that ticket rather than something to
// rediscover.
const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"];
let readme = include_str!("../README.md");
let table: String = readme.lines().filter(|line| line.starts_with('|')).collect();
let missing: Vec<String> = documented_names()
.into_iter()
.filter(|name| !PENDING.contains(&name.as_str()))
.filter(|name| !table.contains(&format!("`worklane {}", name)))
.collect();
assert!(
missing.is_empty(),
"no row in the README command table for {missing:?}. A new command is not \
shipped until the table lists it: that table is the only place a reader \
discovers one, and two commands hid behind an otherwise complete table \
for two minor versions."
);
}
}
+85 -146
View File
@@ -10,6 +10,7 @@ use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
};
use crate::history::{Kind, change, format_history, read_history, write_entry};
use crate::install;
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
use crate::util::*;
@@ -351,99 +352,12 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
Ok(())
}
/// Public for the TUI's detail view, which shows the same comments `show` does.
pub fn read_comments(comments_dir: &Path) -> Result<Vec<(String, String, String, String)>> {
if !comments_dir.exists() {
return Ok(vec![]);
}
let mut comments: Vec<(String, String, String, String)> = Vec::new();
for entry in fs::read_dir(comments_dir)? {
let entry = entry?;
let path = entry.path();
if path.extension().is_some_and(|e| e == "md") {
let content = fs::read_to_string(&path)?;
let filename = path
.file_stem()
.map(|s| s.to_string_lossy().to_string())
.unwrap_or_default();
let author = content
.lines()
.find(|l| l.starts_with("**Author**"))
.and_then(|l| l.split_once("**Author**:"))
.map(|(_, value)| value)
.map(|s| s.trim().to_string())
.unwrap_or_else(|| "unknown".to_string());
let time = content
.lines()
.find(|l| l.starts_with("**Time**"))
.and_then(|l| l.split_once("**Time**:"))
.map(|(_, value)| value)
.map(|s| s.trim().to_string())
.unwrap_or_else(|| "unknown".to_string());
let body = if let Some(after_comment) = content.strip_prefix("**Comment**\n") {
if let Some(end) = after_comment.find("\n\n**Author**") {
after_comment[..end].trim()
} else {
after_comment.trim()
}
} else {
""
};
comments.push((filename, author, time, body.to_string()));
}
}
comments.sort_by(|a, b| a.0.cmp(&b.0));
Ok(comments)
}
/// Write a comment under the first free name derived from `stem`.
///
/// `create_new` rather than `fs::write`: a name that already exists means another
/// comment landed in the same microsecond, and truncating it is exactly the data
/// loss this guards against. The suffix is zero padded so the names keep sorting
/// in the order they were written.
fn write_new_comment(comments_dir: &Path, stem: &str, content: &str) -> Result<String> {
for attempt in 0..100 {
let filename = match attempt {
0 => format!("{}.md", stem),
n => format!("{}_{:02}.md", stem, n),
};
match fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(comments_dir.join(&filename))
{
Ok(mut file) => {
file.write_all(content.as_bytes())?;
return Ok(filename);
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e.into()),
}
}
Err(anyhow!(
"No free comment filename for '{}' in {}",
stem,
comments_dir.display()
))
}
pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
let (_status, title, content) = resolve_ticket(search, worklane_dir)?;
let ticket_uuid = parse_ticket_field(&content, "ID");
// Read before anything is printed, so a board that cannot be read fails instead of
// half printing a ticket.
let resolved = resolved_for(&content, worklane_dir, should_use_colors())?;
let resolved = resolved_for(&content, worklane_dir)?;
// The only title in the output: content_trim_colored used to print it a second
// time from the file content. Green per the colour guideline, and the rule is
@@ -453,9 +367,8 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
println!("\n{}", content_trim_colored(&content, &resolved));
if ticket_uuid != "_Not set_" {
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
let comments = read_comments(&comments_dir)?;
let formatted = format_comments(&comments);
let entries = read_history(worklane_dir, &ticket_uuid)?;
let formatted = format_history(&entries);
println!("{}", formatted);
}
@@ -642,7 +555,13 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
/// A status is a [`Status`] rather than a string, so an unknown one is clap's to refuse
/// and nothing here has to check. What is left is the order of the flow, which is
/// `Status::ALL`.
pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Result<()> {
pub fn cmd_mv(
ticket_id: &str,
target: Status,
force: bool,
actor: &Option<String>,
start: &Path,
) -> Result<()> {
let target_status = target.as_str();
let worklane_dir = find_worklane_dir(start)?;
@@ -712,6 +631,17 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
&title,
)?;
// After the move, never before: an entry for a move that was refused would be a log
// of things that did not happen. The no-op above returns without one for the same
// reason.
write_entry(
&worklane_dir,
&parse_ticket_field(&resolved, "ID"),
Kind::Status,
&change(&current_status, target_status),
&resolve_actor(actor.as_deref()),
)?;
println!(
"Moved ticket '{}' from {} to {}",
color_text(&title, Color::Green),
@@ -725,7 +655,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
pub fn cmd_comment(
ticket_id: &str,
body: &str,
owner: &Option<String>,
actor: &Option<String>,
start: &Path,
) -> Result<()> {
if body.is_empty() {
@@ -740,29 +670,13 @@ pub fn cmd_comment(
return Err(anyhow!("Could not determine ticket ID."));
}
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
fs::create_dir_all(&comments_dir)?;
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
let author = match owner {
Some(o) => o.clone(),
None => get_git_user().unwrap_or_else(|| "unknown".to_string()),
};
let comment_content = format!(
"**Comment**\n\
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n\
",
let filename = write_entry(
&worklane_dir,
&ticket_uuid,
Kind::Comment,
body,
author,
Local::now().format(TIMESTAMP_FORMAT)
);
let filename = write_new_comment(&comments_dir, &stem, &comment_content)?;
&resolve_actor(actor.as_deref()),
)?;
println!("Comment added to '{}' ({})", title, filename);
Ok(())
@@ -996,6 +910,23 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
save_ticket(&worklane_dir, &status, &uuid, &title, renamed, &content)?;
// Tags alone, of everything `set` writes. The other fields change often enough that a
// log of them is noise, and `apply` is what decides this: a field it did not record as
// changed was already what the call asked for. Emptying the field counts, since
// `--clear tags` is the same field going somewhere.
if changed.contains(&"tags") || cleared.contains(&"tags") {
write_entry(
&worklane_dir,
&uuid,
Kind::Tags,
&change(
&parse_ticket_field(&original, "Tags"),
&parse_ticket_field(&content, "Tags"),
),
&resolve_actor(args.actor.as_deref()),
)?;
}
let shown = args.title.clone().unwrap_or(title);
if !changed.is_empty() {
report(&changed, &shown, "Updated");
@@ -1040,6 +971,19 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
// Behind the no-change return above, so a chown to the owner a ticket already has
// records nothing, and after the save, so a failed write logs nothing.
write_entry(
&worklane_dir,
&uuid,
Kind::Owner,
&change(
&parse_ticket_field(&original, "Owner"),
&parse_ticket_field(&content, "Owner"),
),
&resolve_actor(args.actor.as_deref()),
)?;
let verb = match user {
Some(_) => "Updated",
None => "Cleared",
@@ -1565,7 +1509,12 @@ pub fn cmd_campaign_show(search: &str, worklane_dir: &Path) -> Result<()> {
///
/// No-op detection compares the whole file, the way `set` and `chown` do, so assigning
/// a ticket to the campaign it already names writes nothing.
pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Result<()> {
pub fn cmd_assign(
campaign_search: &str,
ticket_id: &str,
actor: &Option<String>,
start: &Path,
) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(campaign_search, &worklane_dir)?;
let (status, title, original) = resolve_ticket(ticket_id, &worklane_dir)?;
@@ -1584,6 +1533,26 @@ pub fn cmd_assign(campaign_search: &str, ticket_id: &str, start: &Path) -> Resul
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
// Behind the no-change return above and after the save, the rule every writer
// follows. The entry records `Campaign::name`, not the uuid the field holds: what
// the reader should see is settled here, when the entry is written. A campaign the
// board no longer has reads `_missing_`, the way the Campaign field itself renders
// a dangling uuid.
let before = match parse_campaign(&original) {
None => NOT_SET.to_string(),
Some(old) => CampaignIndex::load(&worklane_dir)?
.get(&old)
.map(|was| was.name().to_string())
.unwrap_or_else(|| "_missing_".to_string()),
};
write_entry(
&worklane_dir,
&uuid,
Kind::Campaign,
&change(&before, campaign.name()),
&resolve_actor(actor.as_deref()),
)?;
println!(
"Assigned '{}' to campaign '{}'",
color_text(&title, Color::Green),
@@ -1857,33 +1826,3 @@ pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
/// The collision path cannot be provoked from the CLI, since two processes
/// will not share a microsecond, but it is the whole point of the guard.
#[test]
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
let dir = Fixture::new("worklane-test");
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
let third = write_new_comment(&dir, "20260820_143012_123456", "third").unwrap();
assert_eq!(first, "20260820_143012_123456.md");
assert_eq!(second, "20260820_143012_123456_01.md");
assert_eq!(third, "20260820_143012_123456_02.md");
// Nothing was truncated on the way through
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
// read_comments sorts on the stem, so the names must sort in write order
let mut names = vec![second.clone(), third.clone(), first.clone()];
names.sort();
assert_eq!(names, vec![first, second, third]);
}
}
+661
View File
@@ -0,0 +1,661 @@
//! What happened to a ticket, one file per entry.
//!
//! The comments directory was already an append-only log with exactly one event kind:
//! one file per entry under a directory named by the ticket's uuid, stamped to the
//! microsecond and written with `create_new` so two writers cannot clobber each other.
//! This is that log with the kind named in it, so a status change, an owner change, a
//! tag change and a campaign move are recorded beside what somebody said about them.
//!
//! What is deliberately not logged: ticking or unticking a criterion, and edits to the
//! title, description, plan, priority or due. Those change often and a log of them is
//! noise. When one of them matters, whoever made it adds a comment saying why, which is
//! the record actually worth keeping.
//!
//! Every entry names its author, from [`resolve_actor`], so a board several agents write
//! to says which of them did what.
//!
//! [`resolve_actor`]: crate::util::resolve_actor
use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};
use anyhow::{Result, anyhow};
use chrono::Local;
use crate::util::{Cell, Color, TIMESTAMP_FORMAT, paint_cells, should_use_colors};
/// Where a ticket's history lives, under the board.
///
/// Beside the status directories rather than among them, the way `campaigns_dir` is: an
/// entry has no status of its own. Spelled once here, so the writer, the reader and the
/// card's counter cannot disagree about the path.
pub const HISTORY_DIR: &str = "history";
/// The name the same directory had while a comment was the only entry it could hold.
///
/// Kept so a board written by an older version is adopted rather than migrated by hand.
/// See [`adopt_comments`].
pub const COMMENTS_DIR: &str = "comments";
/// How an entry filename is stamped.
///
/// Microseconds, not seconds: at second resolution two entries in the same second
/// produced the same name and the second silently truncated the first. Fixed width and
/// first in the name, so the lexicographic sort in [`read_history`] stays chronological
/// whatever kind follows it.
pub const ENTRY_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
/// The history root of a board.
pub fn history_root(board: &Path) -> PathBuf {
board.join(HISTORY_DIR)
}
/// The history directory for one ticket, named by its full uuid.
pub fn history_dir(board: &Path, uuid: &str) -> PathBuf {
history_root(board).join(uuid)
}
/// What an entry records.
///
/// An enum rather than a string, so a kind the reader does not know is a compile error
/// instead of a word that renders as itself. The variants are the five things worth
/// keeping: what somebody said, and the four fields whose history answers a question.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Kind {
Comment,
Status,
Owner,
Tags,
Campaign,
}
impl Kind {
/// Every kind, which is what the reader matches a marker against and what the
/// counter matches a filename against.
pub const ALL: [Kind; 5] = [
Kind::Comment,
Kind::Status,
Kind::Owner,
Kind::Tags,
Kind::Campaign,
];
/// The width the mechanical labels are padded to, `campaign` being the longest of
/// the four. `comment` renders as a header and a body, not as a row, so it is not
/// among them.
const LABEL_WIDTH: usize = 8;
/// The word in the filename, and the label a mechanical entry renders under.
pub fn slug(self) -> &'static str {
match self {
Kind::Comment => "comment",
Kind::Status => "status",
Kind::Owner => "owner",
Kind::Tags => "tags",
Kind::Campaign => "campaign",
}
}
/// The marker the file opens with, which is what the reader keys the kind off.
///
/// The file is the record and the filename is an index into it: a name can be
/// changed by anything that touches the directory, so the kind is read from the
/// content and only counted from the name.
fn marker(self) -> &'static str {
match self {
Kind::Comment => "**Comment**",
Kind::Status => "**Status**",
Kind::Owner => "**Owner**",
Kind::Tags => "**Tags**",
Kind::Campaign => "**Campaign**",
}
}
}
/// One entry: what happened, who wrote it and when.
#[derive(Debug)]
pub struct Entry {
/// The file stem, which is what the entries are sorted by.
pub filename: String,
pub kind: Kind,
pub author: String,
pub time: String,
/// A comment's text, or the before and after of the field a mechanical entry names.
pub body: String,
}
/// Rename an old `comments` directory to `history`, before anything reads or writes it.
///
/// One rename rather than a migration command: the entries themselves need no rewriting,
/// since [`parse_entry`] reads a file with no marker as the comment it is. Called by the
/// reader, the writer and the counter, so no caller has to remember it and a board can
/// never be reached through a path that skips it.
///
/// Both directories at once is refused rather than merged. Only the CLI writes there, so
/// it cannot arrive at that state on its own, and choosing which of two entries with the
/// same name survives is not a decision to make silently.
pub fn adopt_comments(board: &Path) -> Result<()> {
let old = board.join(COMMENTS_DIR);
if !old.exists() {
return Ok(());
}
let new = history_root(board);
if new.exists() {
return Err(anyhow!(
"Board holds both {} and {}. Only worklane writes there, so this needs a \
person: move the entries under {} into the matching directories in {}, \
then remove it.",
old.display(),
new.display(),
COMMENTS_DIR,
HISTORY_DIR,
));
}
fs::rename(&old, &new)
.map_err(|e| anyhow!("Could not rename {} to {}: {}", old.display(), new.display(), e))
}
/// One entry, from its filename and its content.
///
/// Split out from the directory walk so the parse can be tested without a fixture, and
/// because it is where the compatibility lives: a file with no marker is a comment,
/// which is what every entry written before the kinds existed is.
fn parse_entry(filename: &str, content: &str) -> Entry {
let field = |name: &str| {
let marker = format!("**{}**:", name);
content
.lines()
.find(|line| line.starts_with(&marker))
.and_then(|line| line.split_once(&marker))
.map(|(_, value)| value.trim().to_string())
.unwrap_or_else(|| "unknown".to_string())
};
let kind = Kind::ALL
.into_iter()
.find(|kind| content.starts_with(&format!("{}\n", kind.marker())))
.unwrap_or(Kind::Comment);
let body = content
.strip_prefix(&format!("{}\n", kind.marker()))
.map(|rest| match rest.find("\n\n**Author**") {
Some(end) => rest[..end].trim(),
None => rest.trim(),
})
.unwrap_or("");
Entry {
filename: filename.to_string(),
kind,
author: field("Author"),
time: field("Time"),
body: body.to_string(),
}
}
/// Every entry on a ticket, oldest first.
///
/// Public for the TUI's detail view, which shows the same sequence `show` does.
pub fn read_history(board: &Path, uuid: &str) -> Result<Vec<Entry>> {
adopt_comments(board)?;
let dir = history_dir(board, uuid);
if !dir.exists() {
return Ok(vec![]);
}
let mut entries: Vec<Entry> = Vec::new();
for entry in fs::read_dir(&dir)? {
let path = entry?.path();
if path.extension().is_some_and(|ext| ext == "md") {
let content = fs::read_to_string(&path)?;
let filename = path
.file_stem()
.map(|stem| stem.to_string_lossy().to_string())
.unwrap_or_default();
entries.push(parse_entry(&filename, &content));
}
}
// The stamp is fixed width and leads the name, so this is chronological.
entries.sort_by(|a, b| a.filename.cmp(&b.filename));
Ok(entries)
}
/// The kind a filename names, which is what the count reads instead of the file.
///
/// A stem with no kind in it is a comment, the same compatibility [`parse_entry`] has.
/// The collision suffix is a number and matches no slug, so it is skipped.
fn kind_from_stem(stem: &str) -> Kind {
stem.split('_')
.find_map(|part| Kind::ALL.into_iter().find(|kind| kind.slug() == part))
.unwrap_or(Kind::Comment)
}
/// How many comments a ticket carries, counted off the directory rather than read.
///
/// Comments only, so the card's counter still says how many things somebody said: a
/// ticket that has moved three times has not been talked about. `.md` only, the filter
/// [`read_history`] applies, so a stray file dropped in there is not counted. A missing
/// directory is none, which is what a ticket nothing has happened to has.
pub fn count_comments(board: &Path, uuid: &str) -> usize {
// Swallowed, unlike the reader's: a count is drawn on every card and a board that
// cannot be adopted has to draw as the zero it looks like rather than take the TUI
// down. The next write reports the real reason.
let _ = adopt_comments(board);
let Ok(entries) = fs::read_dir(history_dir(board, uuid)) else {
return 0;
};
entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
.filter(|entry| {
let stem = entry.path().file_stem().map(|s| s.to_string_lossy().to_string());
stem.is_some_and(|stem| kind_from_stem(&stem) == Kind::Comment)
})
.count()
}
/// The file an entry is written as.
///
/// A comment's file is byte for byte what `comment` wrote before the kinds existed, so
/// nothing has to be rewritten and a board can be read by either version.
fn entry_content(kind: Kind, body: &str, author: &str, time: &str) -> String {
format!(
"{}\n\
{}\n\
\n\
**Author**: {}\n\
**Time**: {}\n\
",
kind.marker(),
body,
author,
time
)
}
/// Write an entry under the first free name derived from the stamp.
///
/// `create_new` rather than `fs::write`: a name that already exists means another entry
/// landed in the same microsecond, and truncating it is exactly the data loss this
/// guards against. The suffix is zero padded so the names keep sorting in the order they
/// were written.
fn write_new(dir: &Path, stem: &str, content: &str) -> Result<String> {
for attempt in 0..100 {
let filename = match attempt {
0 => format!("{}.md", stem),
n => format!("{}_{:02}.md", stem, n),
};
match fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(dir.join(&filename))
{
Ok(mut file) => {
file.write_all(content.as_bytes())?;
return Ok(filename);
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e.into()),
}
}
Err(anyhow!("No free entry filename for '{}' in {}", stem, dir.display()))
}
/// Record one entry on a ticket, returning the filename it landed under.
///
/// Called after the edit it describes has been written, never before: an entry for a
/// move that was refused would be a log of things that did not happen. The cost of that
/// order is that a failed write here leaves the edit in place and reports the failure,
/// which is the right way round — the ticket is the record and this is the story of it.
pub fn write_entry(
board: &Path,
uuid: &str,
kind: Kind,
body: &str,
author: &str,
) -> Result<String> {
adopt_comments(board)?;
let dir = history_dir(board, uuid);
fs::create_dir_all(&dir)?;
let now = Local::now();
let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug());
let content = entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string());
write_new(&dir, &stem, &content)
}
/// What a mechanical entry records: the field before the edit and after it.
///
/// The values as the ticket holds them, sentinels included, so `_Not set_` reads the way
/// the field it came from does rather than being translated into a word this module
/// invented.
pub fn change(before: &str, after: &str) -> String {
format!("{} → {}", before, after)
}
pub fn format_history(entries: &[Entry]) -> String {
format_history_with(entries, should_use_colors())
}
/// As above, with the colour decision passed in.
pub fn format_history_with(entries: &[Entry], colored: bool) -> String {
paint_cells(&history_cells(entries), colored)
}
/// The block laid out once, as [`Cell`]s: the CLI paints them and the board turns the
/// same ones into styled spans, so the two views cannot draw two different blocks.
pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
if entries.is_empty() {
return vec![Cell::colored("No history yet.", Color::Grey)];
}
let mut cells = Vec::new();
cells.push(Cell::plain("\n"));
cells.push(Cell::colored("HISTORY", Color::Orange));
cells.push(Cell::plain(format!("\n{}\n", "─".repeat(20))));
for entry in entries {
cells.push(Cell::plain("\n"));
let stamp = format!("{} ({})", entry.author, entry.time);
match entry.kind {
// As it has always read: a header naming who said it, then the text.
Kind::Comment => {
cells.push(Cell::colored(format!("From {}", stamp), Color::Cyan));
cells.push(Cell::plain("\n"));
if !entry.body.is_empty() {
cells.push(Cell::plain(format!(" {}", entry.body)));
}
cells.push(Cell::plain("\n"));
}
// One line: a field change is one fact and a paragraph for it would bury the
// comments it sits between.
_ => {
let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count());
cells.push(Cell::colored(entry.kind.slug(), Color::Orange));
cells.push(Cell::plain(format!("{} ", " ".repeat(padding))));
cells.push(Cell::plain(entry.body.clone()));
cells.push(Cell::plain(" "));
cells.push(Cell::colored(stamp, Color::Cyan));
cells.push(Cell::plain("\n"));
}
}
}
cells
}
#[cfg(test)]
mod tests {
use super::*;
use crate::util::{Fixture, paint};
fn board() -> Fixture {
Fixture::new("worklane-history")
}
#[test]
fn an_entry_names_its_kind_in_the_file_and_in_the_filename() {
let board = board();
let filename =
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude").unwrap();
assert!(filename.ends_with("_status.md"), "was {filename}");
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].kind, Kind::Status);
assert_eq!(entries[0].body, "committed → reviewing");
assert_eq!(entries[0].author, "claude");
}
/// The stamp leads the name and is fixed width, so the kind that follows it cannot
/// reorder the log.
#[test]
fn the_kind_in_the_name_does_not_disturb_the_order() {
let mut names = [
"20260824_120000_000000_status",
"20260824_115959_999999_tags",
"20260824_120000_000001_comment",
];
names.sort();
assert_eq!(
names,
[
"20260824_115959_999999_tags",
"20260824_120000_000000_status",
"20260824_120000_000001_comment",
]
);
}
/// A file written before the kinds existed: no marker, so it is the comment it was,
/// and nothing rewrites it.
#[test]
fn an_entry_with_no_marker_is_a_comment() {
let legacy = parse_entry(
"20260820_143012_123456",
"**Comment**\nSomething said\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
);
assert_eq!(legacy.kind, Kind::Comment);
assert_eq!(legacy.body, "Something said");
assert_eq!(legacy.author, "Ansho Rei");
// And one with no marker at all, which is what `read_comments` read as empty.
let bare = parse_entry("20260820_143012_123457", "notes\n");
assert_eq!(bare.kind, Kind::Comment);
assert_eq!(bare.body, "");
}
/// The comment file is byte for byte what `comment` wrote before this module, which
/// is what lets an old board be read without a migration.
#[test]
fn a_comment_file_is_shaped_as_it_always_was() {
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00");
assert_eq!(
content,
"**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
);
}
/// Same microsecond, three entries: the guard is `create_new`, and the suffix keeps
/// them in the order they were written.
#[test]
fn entries_in_one_microsecond_get_names_of_their_own() {
let board = board();
let dir = history_dir(&board, "uuid");
fs::create_dir_all(&dir).unwrap();
let first = write_new(&dir, "20260820_143012_123456_comment", "first").unwrap();
let second = write_new(&dir, "20260820_143012_123456_comment", "second").unwrap();
let third = write_new(&dir, "20260820_143012_123456_comment", "third").unwrap();
assert_eq!(first, "20260820_143012_123456_comment.md");
assert_eq!(second, "20260820_143012_123456_comment_01.md");
assert_eq!(third, "20260820_143012_123456_comment_02.md");
// Nothing was truncated on the way through
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
// read_history sorts on the stem, so the names must sort in write order
assert!(first < second && second < third, "the names lost their order");
}
#[test]
fn an_old_comments_directory_is_adopted_on_access() {
let board = board();
let comments = board.join(COMMENTS_DIR).join("uuid");
fs::create_dir_all(&comments).unwrap();
fs::write(
comments.join("20260820_143012_123456.md"),
"**Comment**\nOld news\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
)
.unwrap();
let entries = read_history(&board, "uuid").unwrap();
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].body, "Old news");
assert!(!board.join(COMMENTS_DIR).exists(), "the old directory survived");
assert!(history_dir(&board, "uuid").exists(), "the entries did not arrive");
}
/// Refused rather than merged: only the CLI writes there, so this is a board somebody
/// has been in by hand, and picking a survivor per name is not a silent decision.
#[test]
fn a_board_holding_both_directories_is_refused() {
let board = board();
fs::create_dir_all(board.join(COMMENTS_DIR).join("uuid")).unwrap();
fs::create_dir_all(history_dir(&board, "uuid")).unwrap();
let refused = read_history(&board, "uuid");
let message = refused.unwrap_err().to_string();
assert!(
message.contains(COMMENTS_DIR) && message.contains(HISTORY_DIR),
"{message}"
);
}
/// The count is the card's, and a card counts what somebody said.
#[test]
fn only_comments_are_counted() {
let board = board();
write_entry(&board, "uuid", Kind::Comment, "said", "claude").unwrap();
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude").unwrap();
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude").unwrap();
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude").unwrap();
assert_eq!(read_history(&board, "uuid").unwrap().len(), 4);
assert_eq!(count_comments(&board, "uuid"), 1);
}
/// A stem written before the kinds existed counts as the comment it is.
#[test]
fn a_legacy_name_counts_as_a_comment() {
assert_eq!(kind_from_stem("20260820_143012_123456"), Kind::Comment);
assert_eq!(kind_from_stem("20260820_143012_123456_01"), Kind::Comment);
assert_eq!(kind_from_stem("20260820_143012_123456_status"), Kind::Status);
assert_eq!(kind_from_stem("20260820_143012_123456_status_01"), Kind::Status);
}
#[test]
fn a_mechanical_entry_renders_as_one_line_and_a_comment_as_it_did() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
];
let rendered = format_history_with(&entries, false);
assert!(rendered.contains("HISTORY"), "{rendered}");
assert!(
rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"),
"{rendered}"
);
assert!(
rendered
.contains("From Ansho Rei (2026-08-24 12:00:01)\n The offset was never passed"),
"{rendered}"
);
assert!(!rendered.contains('\x1b'), "colour off still painted: {rendered:?}");
}
/// The pin for the cells conversion: `show` prints the block exactly as it printed
/// it before, every painted run spelled out, the way
/// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body.
///
/// Updated once since, deliberately: `campaign` widened the label column from 6 to
/// 8, and the campaign row itself joined the pin (f774a33).
#[test]
fn show_prints_the_same_history_it_printed_before_the_cells_conversion() {
let entries = vec![
parse_entry(
"20260824_120000_000000_status",
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
),
parse_entry(
"20260824_120001_000000_comment",
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
),
parse_entry(
"20260824_120002_000000_campaign",
"**Campaign**\n_Not set_ → v1\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:02\n",
),
];
let expected = format!(
"\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n\n{} _Not set_ → v1 {}\n",
paint("HISTORY", Color::Orange, true),
"─".repeat(20),
paint("status", Color::Orange, true),
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
paint("campaign", Color::Orange, true),
paint("claude (2026-08-24 12:00:02)", Color::Cyan, true),
);
assert_eq!(format_history_with(&entries, true), expected);
assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true));
}
/// Padded to the longest of the four, so every body starts in the same column
/// however short the label above it is.
#[test]
fn the_mechanical_labels_are_aligned() {
let bodies = [
("status", "backlog → committed"),
("owner", "_Not set_ → alice"),
("tags", "bug → bug, cli"),
("campaign", "v1 → beaver"),
];
let entries: Vec<Entry> = bodies
.into_iter()
.map(|(kind, body)| {
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
parse_entry(
&format!("20260824_120000_000000_{kind}"),
&format!(
"{marker}\n{body}\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
),
)
})
.collect();
let rendered = format_history_with(&entries, false);
let columns: Vec<usize> = bodies
.into_iter()
.map(|(_, body)| rendered.find(body).expect("body missing"))
.map(|at| {
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
at - line_start
})
.collect();
assert_eq!(columns.len(), 4);
assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}");
}
#[test]
fn nothing_recorded_says_so() {
assert_eq!(format_history_with(&[], false), "No history yet.");
}
}
+9 -4
View File
@@ -6,6 +6,7 @@ mod clipboard;
mod command;
mod completions;
mod handlers;
mod history;
mod install;
mod tag;
mod tui;
@@ -56,15 +57,17 @@ fn main() -> Result<()> {
let worklane_dir = find_worklane_dir(&start)?;
cmd_show(&id, &worklane_dir)
}
Some(Command::Mv { ticket, status, force }) => cmd_mv(&ticket, status, force, &start),
Some(Command::Mv { ticket, status, force, actor }) => {
cmd_mv(&ticket, status, force, &actor, &start)
}
Some(Command::Set(args)) => cmd_set(&args, &start),
Some(Command::Append(args)) => cmd_append(&args, &start),
Some(Command::Relate(args)) => cmd_relate(&args, &start),
Some(Command::Chown(args)) => cmd_chown(&args, &start),
Some(Command::Check(args)) => cmd_check(&args, true, &start),
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
Some(Command::Comment { ticket, body, owner }) => {
cmd_comment(&ticket, &body, &owner, &start)
Some(Command::Comment { ticket, body, actor }) => {
cmd_comment(&ticket, &body, &actor, &start)
}
Some(Command::Campaign { command }) => match command {
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
@@ -79,7 +82,9 @@ fn main() -> Result<()> {
cmd_campaign_show(&campaign, &worklane_dir)
}
},
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
Some(Command::Assign { campaign, ticket, actor }) => {
cmd_assign(&campaign, &ticket, &actor, &start)
}
// The bare form and `ls` are one arm: `worklane tags` was the listing before the
// group existed and the fish completion still calls it that way, so the two
// spellings cannot be allowed to drift into two behaviours.
+229 -49
View File
@@ -21,7 +21,7 @@ use ratatui::text::{Line, Span, Text};
use ratatui::widgets::{Block, Borders, Clear, Paragraph, Tabs, Wrap};
use crate::campaign::{CAMPAIGNS_DIR, CampaignIndex, Standing};
use crate::handlers::read_comments;
use crate::history::{history_cells, history_root, read_history};
use crate::tag::{NO_ANNOTATION, TAGS_FILE, TagIndex};
use crate::util::*;
@@ -1885,10 +1885,10 @@ impl Board {
}
/// The ticket as the detail view holds it: its name and short id, then the body as
/// `show` renders it and the comments.
/// `show` renders it and the history.
///
/// Plain rather than coloured, since ratatui draws styled spans and an escape sequence
/// in a paragraph would be printed as literal bytes.
/// Styled spans rather than painted text, since an escape sequence in a ratatui
/// paragraph would be printed as literal bytes.
fn detail_of(card: &Card) -> Detail {
let ticket = &card.ticket;
let content = std::fs::read_to_string(&ticket.path).unwrap_or_default();
@@ -1902,19 +1902,21 @@ fn detail_of(card: &Card) -> Detail {
// read of one small directory beside it, for the same reason `show` pays it: the
// field stores a uuid, and a card that displayed one raw would say nothing.
let resolved = worklane_dir
.and_then(|dir| crate::campaign::resolved_for(&content, dir, false).ok())
.and_then(|dir| crate::campaign::resolved_for(&content, dir).ok())
.unwrap_or_default();
let comments = match worklane_dir {
Some(worklane_dir) => {
read_comments(&worklane_dir.join("comments").join(&uuid)).unwrap_or_default()
}
let history = match worklane_dir {
Some(worklane_dir) => read_history(worklane_dir, &uuid).unwrap_or_default(),
None => Vec::new(),
};
// Colour off for the text, which is what keeps escapes out of the paragraph, and the
// relations arrive as rows so the board can style them itself.
let mut parts = content_parts(&content, false, &resolved);
parts.push(BodyPart::Text(format!("\n{}", format_comments_with(&comments, false))));
// Colour on, and nothing here is painted: the body arrives as cells, the relations
// as rows and the history block as the cells the CLI paints, and `detail_body`
// turns them all into styled spans. An escape sequence never enters, which is what
// a ratatui paragraph would draw as literal bytes.
let mut parts = content_parts(&content, true, &resolved);
let mut block = vec![Cell::plain("\n")];
block.extend(history_cells(&history));
parts.push(BodyPart::Cells(block));
Detail {
title: ticket.title.clone(),
@@ -1936,17 +1938,19 @@ fn detail_body(parts: &[BodyPart]) -> Text<'static> {
for part in parts {
match part {
BodyPart::Text(text) => {
let mut rest = text.as_str();
while let Some((line, tail)) = rest.split_once('\n') {
if !line.is_empty() {
open.push(Span::raw(line.to_string()));
BodyPart::Cells(cells) => {
for cell in cells {
let mut rest = cell.text.as_str();
while let Some((line, tail)) = rest.split_once('\n') {
if !line.is_empty() {
open.push(span_from(line, cell.color));
}
lines.push(Line::from(std::mem::take(&mut open)));
rest = tail;
}
if !rest.is_empty() {
open.push(span_from(rest, cell.color));
}
lines.push(Line::from(std::mem::take(&mut open)));
rest = tail;
}
if !rest.is_empty() {
open.push(Span::raw(rest.to_string()));
}
}
// One line each, from the same cells `render_relations` paints, so the block
@@ -1972,10 +1976,26 @@ fn detail_body(parts: &[BodyPart]) -> Text<'static> {
/// The other half of `paint_cells`, which is the CLI's. `From<Color>` is what makes the
/// two agree about what the colour is.
fn span_of(cell: Cell) -> Span<'static> {
match cell.color {
Some(color) => Span::styled(cell.text, Style::default().fg(color.into())),
None => Span::raw(cell.text),
span_from(cell.text, cell.color)
}
/// The same, for a renderer holding the two halves of a cell rather than the cell.
///
/// The bold on magenta is not a flourish. `Color::Magenta.ansi()` is `\x1b[1;35m`, so
/// the CLI draws every bold run bold as well as magenta, and a board that dropped the
/// modifier would be painting the same cell differently from the CLI. The colour is the
/// only thing `From<Color>` can carry, so the attribute has to be added on this side.
fn span_from(text: impl Into<String>, color: Option<Color>) -> Span<'static> {
let Some(color) = color else {
return Span::raw(text.into());
};
let mut style = Style::default().fg(color.into());
if color == Color::Magenta {
style = style.add_modifier(Modifier::BOLD);
}
Span::styled(text.into(), style)
}
/// The four columns of one board, with each card's campaign already named.
@@ -2189,7 +2209,7 @@ fn retain_campaign(mut columns: Vec<Column>, campaign: Option<&str>) -> Vec<Colu
/// The label for the campaign a ticket names, or nothing when it names none.
///
/// Nothing, too, for a uuid the index does not hold. `campaign_cell` renders that case as
/// Nothing, too, for a uuid the index does not hold. `campaign_cells` renders that case as
/// `_missing_` because a metadata table is a place to report a dangling reference; a card
/// is not, and the answer here is the one `mark_blocked` gives a blocker nobody holds.
fn campaign_of(ticket: &TicketItem, campaigns: &CampaignIndex) -> Option<Cell> {
@@ -2369,9 +2389,8 @@ pub fn digest(worklane_dir: &Path) -> u64 {
// the picker, and a codename edited by hand has to reach every card that names it.
visit(worklane_dir.join(CAMPAIGNS_DIR));
// Comments live one level deeper, a directory per ticket.
let comments = worklane_dir.join("comments");
if let Ok(read) = std::fs::read_dir(&comments) {
// History entries live one level deeper, a directory per ticket.
if let Ok(read) = std::fs::read_dir(history_root(worklane_dir)) {
for entry in read.filter_map(|e| e.ok()) {
visit(entry.path());
}
@@ -4128,20 +4147,20 @@ mod tests {
/// The ticket `write_card`, `write_tagged_card` and `write_member_card` all write.
///
/// A const rather than a literal in each, now that a test has to name it from outside
/// them: the comments of a ticket live in a directory named by its uuid, so a fixture
/// them: the history of a ticket lives in a directory named by its uuid, so a fixture
/// that wrote a different one would silently count nothing.
const FIXTURE_UUID: &str = "11111111-0000-4000-8000-000000000000";
/// Comments where `comment` puts them: under the board, in a directory named by the
/// ticket's uuid, one `.md` per comment. The fixture uuid, since that is what
/// ticket's uuid, one `.md` per entry. The fixture uuid, since that is what
/// `write_card` writes into the ID field the counter reads.
fn write_comments(dir: &Path, count: usize) {
let comments = comments_dir(dir, FIXTURE_UUID);
std::fs::create_dir_all(&comments).unwrap();
let history = crate::history::history_dir(dir, FIXTURE_UUID);
std::fs::create_dir_all(&history).unwrap();
for n in 0..count {
std::fs::write(
comments.join(format!("20260823_1200{n:02}_000000.md")),
history.join(format!("20260823_1200{n:02}_000000_comment.md")),
format!("**Comment**\n\n**Author**: alice\n**Time**: 2026-08-23 12:00:{n:02}\n\nSaid {n}.\n"),
)
.unwrap();
@@ -4496,7 +4515,7 @@ mod tests {
write_comments(&dir, 2);
let board = one_board(&dir);
std::fs::remove_dir_all(comments_dir(&dir, FIXTURE_UUID)).unwrap();
std::fs::remove_dir_all(crate::history::history_dir(&dir, FIXTURE_UUID)).unwrap();
let card = board.selected().expect("no card");
let rows: Vec<String> = card_lines(card, false, 40)
@@ -4645,10 +4664,10 @@ mod tests {
write_ticket(&dir, "backlog", uuid, "First one", "");
let before = digest(&dir);
let comments = comments_dir(&dir, uuid);
std::fs::create_dir_all(&comments).unwrap();
let history = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&history).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
history.join("20260821_120000_000000_comment.md"),
"**Comment**\nA note from elsewhere.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
@@ -4883,10 +4902,10 @@ mod tests {
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", "");
let comments = dir.join("comments").join(uuid);
let comments = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
comments.join("20260821_120000_000000_comment.md"),
"**Comment**\nA note from elsewhere.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
@@ -4913,6 +4932,94 @@ mod tests {
assert!(board.detail.is_none());
}
/// The detail view shows the sequence `show` does, mechanical entries included, so a
/// reader on the board sees how a ticket got where it is and not only what was said
/// about it.
#[test]
fn the_detail_view_shows_a_field_change_beside_a_comment() {
let dir = board_dir();
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", "");
let history = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&history).unwrap();
std::fs::write(
history.join("20260821_120000_000000_status.md"),
"**Status**\nbacklog → committed\n\n**Author**: claude\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
std::fs::write(
history.join("20260821_120001_000000_comment.md"),
"**Comment**\nAnd why.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:01\n",
)
.unwrap();
let mut board = one_board(&dir);
board.toggle_detail();
let plain = board.detail.as_ref().expect("no detail").plain();
assert!(plain.contains("HISTORY"), "{plain}");
assert!(plain.contains("status backlog → committed claude ("), "{plain}");
let moved = plain.find("backlog → committed").expect("the move is missing");
let said = plain.find("And why.").expect("the comment is missing");
assert!(moved < said, "the board reordered the log:\n{plain}");
assert!(!plain.contains('\x1b'), "escapes reached the detail view: {plain:?}");
}
/// The history block was the last flat part of the overlay, f3e099e: the board
/// appended it as a pre-rendered string after the body, so it drew plain under a
/// body e4d0bb7 had fully styled. It arrives as cells now, in the colours `show`
/// paints.
///
/// Paired the way the guideline demands: a renderer that dropped every colour would
/// pass the no-escape half, so the presence is asserted beside it.
#[test]
fn the_history_block_is_styled_in_the_overlay_and_no_escape_reached_it() {
let dir = board_dir();
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", "");
let history = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&history).unwrap();
std::fs::write(
history.join("20260821_120000_000000_status.md"),
"**Status**\nbacklog → committed\n\n**Author**: claude\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
std::fs::write(
history.join("20260821_120001_000000_comment.md"),
"**Comment**\nAnd why.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:01\n",
)
.unwrap();
let mut board = one_board(&dir);
board.toggle_detail();
let detail = board.detail.as_ref().expect("no detail");
let heading = body_line(detail, "HISTORY");
assert_eq!(span_color(&heading, "HISTORY"), Some(Color::Orange.into()));
let from = body_line(detail, "From bob");
assert_eq!(
span_color(&from, "From bob (2026-08-21 12:00:01)"),
Some(Color::Cyan.into())
);
let change = body_line(detail, "backlog → committed");
assert_eq!(span_color(&change, "status"), Some(Color::Orange.into()));
assert_eq!(
span_color(&change, "claude (2026-08-21 12:00:00)"),
Some(Color::Cyan.into())
);
// The other half: the colour arrived as styles, not as bytes.
assert!(
!detail.plain().contains('\x1b'),
"escapes reached the detail view: {:?}",
detail.plain()
);
}
/// The reported bug: the modal showed a description, criteria and a metadata
/// table belonging to a ticket it never named.
#[test]
@@ -5002,10 +5109,10 @@ mod tests {
board.toggle_detail();
assert!(!board.detail.as_ref().unwrap().plain().contains("A late note."));
let comments = dir.join("comments").join(uuid);
let comments = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
comments.join("20260821_120000_000000_comment.md"),
"**Comment**\nA late note.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
@@ -5035,10 +5142,10 @@ mod tests {
let uuid = "11111111-0000-4000-8000-000000000000";
write_ticket(&dir, "backlog", uuid, "First one", &long_section(60));
let comments = dir.join("comments").join(uuid);
let comments = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
comments.join("20260821_120000_000000_comment.md"),
"**Comment**\nThe last word.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
@@ -5206,10 +5313,10 @@ mod tests {
board.scroll_detail(1, SCREEN);
let offset = board.offset;
let comments = dir.join("comments").join(uuid);
let comments = crate::history::history_dir(&dir, uuid);
std::fs::create_dir_all(&comments).unwrap();
std::fs::write(
comments.join("20260821_120000_000000.md"),
comments.join("20260821_120000_000000_comment.md"),
"**Comment**\nA late note.\n\n**Author**: bob\n**Time**: 2026-08-21 12:00:00\n",
)
.unwrap();
@@ -6584,7 +6691,7 @@ mod tests {
}
assert_eq!(board.offset, last, "the clamp and the body disagree");
// The relations sit at the end of this fixture, so the last row and the comments
// The relations sit at the end of this fixture, so the last row and the history
// line are what the last screenful has to hold.
let screen = render(&board, SCREEN.width, SCREEN.height).join("\n");
assert!(
@@ -6592,7 +6699,7 @@ mod tests {
"the last relation is not on screen:\n{screen}"
);
assert!(
screen.contains("No comments yet."),
screen.contains("No history yet."),
"the body ends past the last screenful:\n{screen}"
);
}
@@ -6658,6 +6765,79 @@ mod tests {
);
}
/// Every painted run in the body reaches the overlay as a style, e4d0bb7.
///
/// The block was the only coloured part of the body; the rest was flat because
/// `content_parts` painted into a string and the board had to ask for the unpainted
/// one. It hands out cells now, so the CLI paints them and the board styles them,
/// and there is one layout behind both.
///
/// Paired the way the guideline demands, and both halves are load bearing here: a
/// renderer that dropped every colour would pass the absence, and one that went back
/// to painting strings would pass the presence.
#[test]
fn the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it() {
let dir = board_dir();
let uuid = "11111111-0000-4000-8000-000000000000";
std::fs::write(
dir.join("backlog").join(format!("{uuid}_a-painted-one.md")),
format!(
"# A painted one\n\n## Description\n\nA line with **emphasis** in it.\n\n\
## Acceptance Criteria\n\n- [ ] Something\n\n\
## Implementation Plan\n\n1. A step\n\n\
## Metadata\n\n- **ID**: {uuid}\n- **Due**: _Not set_\n\
- **Tags**: bug\n- **Status**: backlog\n"
),
)
.unwrap();
let mut board = one_board(&dir);
board.toggle_detail();
let detail = board.detail.as_ref().expect("no detail");
// One run per colour the guideline gives the body, each asked for by name so a
// run that goes flat names itself in the failure.
let heading = body_line(detail, "Description");
assert_eq!(span_color(&heading, "Description"), Some(Color::Orange.into()));
let emphasis = body_line(detail, "emphasis");
assert_eq!(span_color(&emphasis, "emphasis"), Some(Color::Magenta.into()));
let criterion = body_line(detail, "Something");
assert_eq!(span_color(&criterion, "1."), Some(Color::Cyan.into()));
assert_eq!(span_color(&criterion, "[ ]"), Some(Color::Grey.into()));
let step = body_line(detail, "A step");
assert_eq!(span_color(&step, "1."), Some(Color::Cyan.into()));
let due = body_line(detail, "_Not set_");
assert_eq!(span_color(&due, "Due"), Some(Color::Red.into()));
assert_eq!(span_color(&due, "_Not set_"), Some(Color::Grey.into()));
let tags = body_line(detail, "bug");
assert_eq!(span_color(&tags, "bug"), Some(tag_color("bug").into()));
// `Color::Magenta.ansi()` is `\x1b[1;35m`, so the CLI draws a bold run bold as
// well as magenta. The board has to add the modifier itself, since `From<Color>`
// carries only the colour.
let bold = emphasis
.spans
.iter()
.find(|span| span.content.as_ref() == "emphasis")
.expect("no emphasis span");
assert!(
bold.style.add_modifier.contains(Modifier::BOLD),
"the bold run is magenta but not bold: {bold:?}"
);
// The other half: none of that arrived as bytes.
assert!(
!detail.plain().contains('\x1b'),
"escapes reached the body: {:?}",
detail.plain()
);
}
/// A target the board no longer holds keeps the id, which is the only thing left to
/// go looking for, and says `_missing_` in the grey that means an unset value. The
/// colour must not turn a gap into something that reads like a real target.
+431 -202
View File
@@ -5,29 +5,10 @@ use std::io::IsTerminal;
use std::path::Path;
use std::sync::OnceLock;
/// How timestamps are written into tickets and comments, and therefore how they
/// are read back. Shared so the writer and the reader cannot drift apart.
/// How timestamps are written into tickets and history entries, and therefore how
/// they are read back. Shared so the writer and the reader cannot drift apart.
pub const TIMESTAMP_FORMAT: &str = "%Y-%m-%d %H:%M:%S";
/// How a comment filename is stamped.
///
/// Microseconds, not seconds: at second resolution two comments in the same
/// second produced the same name and the second silently truncated the first.
/// Fixed width, so the lexicographic sort in `read_comments` stays chronological.
pub const COMMENT_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
/// Where a ticket's comments live, under the board.
///
/// Beside the status directories rather than among them, the way `campaigns_dir` is: a
/// comment has no status of its own. Spelled once here, so the writer, the reader and the
/// card's counter cannot disagree about the path.
pub const COMMENTS_DIR: &str = "comments";
/// The comments directory for one ticket, named by its full uuid.
pub fn comments_dir(board: &Path, uuid: &str) -> std::path::PathBuf {
board.join(COMMENTS_DIR).join(uuid)
}
/// The mark a card puts after its comment count.
///
/// A closing quotation ornament, so `2\u{275e}` reads as two things somebody said rather
@@ -416,6 +397,63 @@ pub fn get_git_user() -> Option<String> {
}
})
}
/// The variable that names the writer of an entry, set once per session.
///
/// A per-call flag can be forgotten on the fortieth call; a variable set by an agent's
/// own configuration is inherited by every call it makes.
pub const ACTOR_ENV: &str = "WORKLANE_ACTOR";
/// The author written when nothing names one.
pub const UNKNOWN_ACTOR: &str = "unknown";
/// The actor for the whole run: the variable, then the git user.
///
/// Split out from the caching wrapper for the reason `colors_wanted` is: a threaded test
/// binary cannot mutate the process environment to reach one branch at a time.
///
/// An empty `WORKLANE_ACTOR` counts as unset, the convention `colors_wanted` follows for
/// `NO_COLOR`, so a wrapper script can clear an inherited one. `git_user` is a closure
/// rather than a value because the fallback costs a subprocess and the variable usually
/// answers first.
fn session_actor(env: Option<&str>, git_user: impl FnOnce() -> Option<String>) -> Option<String> {
match env.map(str::trim).filter(|value| !value.is_empty()) {
Some(value) => Some(value.to_string()),
None => git_user(),
}
}
/// The actor for one entry: the flag wins, otherwise the session's, otherwise unknown.
///
/// Free text, validated against nothing, the way the `chown` user is: there is no
/// registry of actors to check a name against.
fn entry_actor(flag: Option<&str>, session: Option<&str>) -> String {
[flag, session]
.into_iter()
.flatten()
.map(str::trim)
.find(|value| !value.is_empty())
.unwrap_or(UNKNOWN_ACTOR)
.to_string()
}
/// Who to attribute an entry to, from the flag the call carried.
///
/// Precedence: flag, then `WORKLANE_ACTOR`, then the git user, then `unknown`. Every
/// entry the CLI writes goes through here, so a board several agents write to says which
/// of them wrote what instead of attributing all of it to one human.
pub fn resolve_actor(flag: Option<&str>) -> String {
// The session half is decided once, the way should_use_colors is: neither input can
// change mid-run, and the git user costs a subprocess.
static SESSION: OnceLock<Option<String>> = OnceLock::new();
let session = SESSION.get_or_init(|| {
let env = std::env::var(ACTOR_ENV).ok();
session_actor(env.as_deref(), get_git_user)
});
entry_actor(flag, session.as_deref())
}
/// One file a search matched, and where it was found.
pub struct Found {
/// The name the match is reported under: the status directory for a ticket, and
@@ -606,37 +644,6 @@ pub fn resolve_ticket(search: &str, worklane_dir: &Path) -> Result<(String, Stri
let found = matches.remove(0);
Ok((found.dir, found.title, found.content))
}
pub fn format_comments(comments: &[(String, String, String, String)]) -> String {
format_comments_with(comments, should_use_colors())
}
/// As above, with the colour decision passed in for the TUI.
pub fn format_comments_with(
comments: &[(String, String, String, String)],
colored: bool,
) -> String {
if comments.is_empty() {
return paint("No comments yet.", Color::Grey, colored);
}
let mut result = String::new();
result.push('\n');
result.push_str(&paint("COMMENTS", Color::Orange, colored));
result.push_str(&format!("\n{}\n", "─".repeat(20)));
for (_filename, author, time, body) in comments {
result.push('\n');
result.push_str(&paint(&format!("From {} ({})", author, time), Color::Cyan, colored));
result.push('\n');
if !body.is_empty() {
result.push_str(" ");
result.push_str(body);
}
result.push('\n');
}
result
}
/// The parts of a ticket's body that cannot be rendered from the file alone.
///
/// Both are resolved against the rest of the board. The Relations section stores one
@@ -656,9 +663,11 @@ pub struct Resolved {
/// Rows rather than the rendered block: the CLI paints them into escapes and the
/// board styles the same rows itself, since a paragraph is no place for an escape.
pub relations: Vec<RelationRow>,
/// The Campaign value as it reads, from [`reference_cell`]. Empty leaves the stored
/// The Campaign value as it reads, from [`campaign_cells`]. Empty leaves the stored
/// value to render as it sits, which is what a ticket in no campaign wants.
pub campaign: String,
///
/// [`campaign_cells`]: crate::campaign::campaign_cells
pub campaign: Vec<Cell>,
}
pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
@@ -670,35 +679,32 @@ pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
/// The rule is measured on the name as displayed, in characters. It used to span the
/// raw line, so it ran three past the heading for the `## `, and byte length over-drew
/// anything non-ASCII.
fn push_heading(out: &mut Body, heading: &str, colored: bool) {
fn push_heading(out: &mut Body, heading: &str) {
let name = heading.strip_prefix("## ").unwrap_or(heading);
out.push_str(&paint(name, Color::Orange, colored));
out.push_cell(Cell::colored(name, Color::Orange));
out.push('\n');
out.push_str(&"─".repeat(name.chars().count()));
out.push('\n');
out.push('\n');
}
/// The ticket body rendered for display, with the colour decision passed in.
/// One piece of the rendered body: a run of cells, or relations still as rows.
///
/// The TUI needs the plain form: ratatui draws styled spans, and an escape sequence
/// embedded in a paragraph would be printed as literal bytes.
/// The body is one string to the CLI and a run of styled lines to the board. Neither
/// half is rendered here: a [`Cell`] carries the text and the colour it is drawn in, and
/// the renderer decides what a colour is, an escape sequence for the CLI and a ratatui
/// style for the board. That is what makes the two views one layout rather than two
/// that have to be kept in step.
///
/// [`Resolved`] carries the parts that come from elsewhere on the board, since the
/// body alone cannot render them.
/// One piece of the rendered body: text as it prints, or relations still as rows.
///
/// The body is one string to the CLI and a run of styled lines to the board, and the
/// only part that differs is the relations block. Splitting the body here rather than
/// building it twice is what keeps the two views from drifting: everything outside the
/// block is rendered once, by [`content_parts`], and the rows are handed on unpainted.
/// The relations stay rows rather than becoming cells here because their layout needs
/// the whole block at once: the label column is padded to the widest label.
pub enum BodyPart {
Text(String),
Cells(Vec<Cell>),
Relations(Vec<RelationRow>),
}
/// The body under construction. Text accumulates into the trailing run, and a relations
/// The body under construction. Cells accumulate into the trailing run, and a relations
/// block closes it, so a caller pushes text and rows without tracking which it pushed
/// last.
#[derive(Default)]
@@ -707,17 +713,37 @@ struct Body {
}
impl Body {
/// A run in the default foreground.
fn push_str(&mut self, text: &str) {
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push_str(text),
_ => self.parts.push(BodyPart::Text(text.to_string())),
}
self.push_cell(Cell::plain(text));
}
fn push(&mut self, c: char) {
self.push_cell(Cell::plain(c.to_string()));
}
/// One run, merged into the trailing cell when it is the same colour.
///
/// Merging is not an optimisation. The board draws a span per cell, and the body is
/// pushed a character at a time in places, so without this a plain line arrives as
/// forty single-character spans for ratatui to wrap.
fn push_cell(&mut self, cell: Cell) {
if cell.text.is_empty() {
return;
}
match self.parts.last_mut() {
Some(BodyPart::Text(run)) => run.push(c),
_ => self.parts.push(BodyPart::Text(c.to_string())),
Some(BodyPart::Cells(cells)) => match cells.last_mut() {
Some(last) if last.color == cell.color => last.text.push_str(&cell.text),
_ => cells.push(cell),
},
_ => self.parts.push(BodyPart::Cells(vec![cell])),
}
}
fn push_cells(&mut self, cells: Vec<Cell>) {
for cell in cells {
self.push_cell(cell);
}
}
@@ -727,26 +753,42 @@ impl Body {
/// Whether the text written so far ends with `suffix`. A relations block never does,
/// since it is not text yet.
///
/// Over the whole trailing run rather than its last cell: a colour change starts a
/// new cell, and the question here is what the body reads like, not how it is split.
fn ends_with(&self, suffix: &str) -> bool {
match self.parts.last() {
Some(BodyPart::Text(run)) => run.ends_with(suffix),
Some(BodyPart::Cells(cells)) => {
let run: String = cells.iter().map(|cell| cell.text.as_str()).collect();
run.ends_with(suffix)
}
_ => false,
}
}
}
/// The ticket body as the CLI prints it.
///
/// [`Resolved`] carries the parts that come from elsewhere on the board, since the
/// body alone cannot render them.
pub fn content_trim(content: &str, colored: bool, resolved: &Resolved) -> String {
content_parts(content, colored, resolved)
.iter()
.map(|part| match part {
BodyPart::Text(text) => text.clone(),
BodyPart::Cells(cells) => paint_cells(cells, colored),
BodyPart::Relations(rows) => render_relations(rows, colored),
})
.collect()
}
/// The body rendered into its parts, with the colour decision already applied to the
/// text and deliberately not to the relations.
/// The body laid out as cells, for a renderer to colour as it colours anything.
///
/// `colored` no longer paints anything here, and it is not the CLI's flag: it says
/// whether *this* renderer can carry a colour at all, which is the one question the
/// layout still turns on. `**bold**` and `[text](url)` give their markers up to a
/// colour, so a renderer with no colour has to keep them, or the emphasis is lost
/// rather than moved. The board passes `true`, since it styles spans; `content_trim`
/// passes the CLI's decision, so a piped `show` still reads its markers.
pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<BodyPart> {
let relations = resolved.relations.as_slice();
let lines: Vec<&str> = content.trim().lines().collect();
@@ -772,24 +814,20 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
// file would have kept it, ahead of the metadata, rather than tacked on
// after everything.
if is_metadata_heading(line) && !stores_relations && !relations.is_empty() {
push_heading(&mut result, RELATIONS.heading, colored);
push_heading(&mut result, RELATIONS.heading);
result.push_relations(relations);
result.push('\n');
shown_relations = true;
}
push_heading(&mut result, section_name, colored);
push_heading(&mut result, section_name);
i += 1;
// Metadata is rendered as a block, so it is consumed here rather than
// falling through to the line-at-a-time cases below.
if is_metadata_heading(line) {
let end = section_end(&lines, i);
result.push_str(&render_metadata_table(
&lines[i..end],
colored,
&resolved.campaign,
));
result.push_cells(metadata_cells(&lines[i..end], colored, &resolved.campaign));
i = end;
}
@@ -825,7 +863,7 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
// Implementation Plan - color numbers in cyan
if current_section == "## Implementation Plan" {
result.push_str(&colorize_ordered(line, colored));
result.push_cells(ordered_cells(line));
result.push('\n');
continue;
}
@@ -837,17 +875,17 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
&& let Some((checked, text)) = checkbox(line)
{
criterion += 1;
result.push_str(&paint(&format!("{}.", criterion), Color::Cyan, colored));
result.push_cell(Cell::colored(format!("{}.", criterion), Color::Cyan));
result.push(' ');
result.push_str(&paint(if checked { "[x]" } else { "[ ]" }, Color::Grey, colored));
result.push_cell(Cell::colored(if checked { "[x]" } else { "[ ]" }, Color::Grey));
result.push(' ');
result.push_str(&colorize_inline(text, colored));
result.push_cells(inline_cells(text, colored));
result.push('\n');
continue;
}
// Regular content, with its inline markup coloured in place.
result.push_str(&colorize_inline(line, colored));
// Regular content, with its inline markup carried as cells of its own.
result.push_cells(inline_cells(line, colored));
result.push('\n');
}
@@ -857,42 +895,42 @@ pub fn content_parts(content: &str, colored: bool, resolved: &Resolved) -> Vec<B
if !result.ends_with("\n\n") {
result.push('\n');
}
push_heading(&mut result, RELATIONS.heading, colored);
push_heading(&mut result, RELATIONS.heading);
result.push_relations(relations);
}
result.parts
}
/// Colour the `1.` at the head of a numbered line, leaving the rest alone.
/// The `1.` at the head of a numbered line as a cell of its own, the rest as it stands.
///
/// Takes the decision rather than asking for it. Asking is what put `\x1b[36m` and
/// `\x1b[0m` around every Implementation Plan number in the board's detail view,
/// which renders with colour off precisely because a paragraph is not a place an
/// escape sequence can go.
fn colorize_ordered(line: &str, colored: bool) -> String {
/// No colour flag. The cell says cyan and the renderer decides what cyan is, which is
/// what stopped this asking `should_use_colors()` and putting `\x1b[36m` around every
/// Implementation Plan number in the board's detail view.
fn ordered_cells(line: &str) -> Vec<Cell> {
if line.chars().next().is_none_or(|c| !c.is_ascii_digit()) {
return line.to_string();
return vec![Cell::plain(line)];
}
// Match "1. " pattern and color the number in cyan
let mut result = String::new();
// Match "1. " pattern and colour the number in cyan
let chars: Vec<char> = line.chars().collect();
for (i, c) in chars.iter().enumerate() {
if c.is_ascii_digit() {
// still scanning digits
} else if *c == '.' && i + 1 < chars.len() && chars[i + 1] == ' ' {
let number = &line[..i + 1];
result.push_str(&paint(number, Color::Cyan, colored));
result.push_str(&line[i + 1..]);
return result;
// Byte indexing on a char index, which holds because everything walked to
// get here is an ASCII digit or the dot itself.
return vec![
Cell::colored(&line[..i + 1], Color::Cyan),
Cell::plain(&line[i + 1..]),
];
} else {
break;
}
}
line.to_string()
vec![Cell::plain(line)]
}
/// Space between a label column and the value beside it, in the metadata table and in
@@ -930,33 +968,36 @@ fn metadata_row(line: &str) -> MetadataRow<'_> {
/// `campaign` is the resolved cell for the Campaign field, empty when there is none.
/// The file stores the full uuid, per the rule the Relations section already follows,
/// so a bare value here would be thirty-six characters saying nothing.
fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -> String {
fn metadata_value_cells(name: &str, value: &str, campaign: &[Cell]) -> Vec<Cell> {
if name == CAMPAIGN_FIELD && !campaign.is_empty() {
return campaign.to_string();
return campaign.to_vec();
}
if name == "Priority" {
// Reads as a glyph, while the file keeps storing the number.
let (glyph, colour) = priority_mark(priority_from_value(value));
return format!("{} {}", paint(glyph, colour, colored), value);
return vec![
Cell::colored(glyph, colour),
Cell::plain(format!(" {}", value)),
];
}
if is_unknown_value(value) {
return paint(value, Color::Grey, colored);
return vec![Cell::colored(value, Color::Grey)];
}
// The same word in the same colour as the label a card draws, since `tag_color` is a
// pure function of it. No mark here: the field name has already said what this is,
// and the mark is what tells a campaign from a tag on a row that holds both.
if name == CODENAME_FIELD {
return paint(value, tag_color(value), colored);
return vec![Cell::colored(value, tag_color(value))];
}
if name == "Tags" {
return paint_tags(value, colored);
return tag_cells(value);
}
value.to_string()
vec![Cell::plain(value)]
}
/// The stored tag list with each tag in its own colour.
@@ -965,25 +1006,28 @@ fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -
/// holds come back unchanged. `bug, cli` and `bug,cli` are both written by hand at some
/// point, and a cell that normalised them would be the display quietly disagreeing with
/// the file it is showing.
fn paint_tags(value: &str, colored: bool) -> String {
value
.split(',')
.map(|piece| {
let tag = piece.trim();
if tag.is_empty() {
return piece.to_string();
}
fn tag_cells(value: &str) -> Vec<Cell> {
let mut cells = Vec::new();
let lead = piece.len() - piece.trim_start().len();
format!(
"{}{}{}",
&piece[..lead],
paint(tag, tag_color(tag), colored),
&piece[lead + tag.len()..]
)
})
.collect::<Vec<_>>()
.join(",")
for (index, piece) in value.split(',').enumerate() {
if index > 0 {
cells.push(Cell::plain(","));
}
let tag = piece.trim();
if tag.is_empty() {
cells.push(Cell::plain(piece));
continue;
}
let lead = piece.len() - piece.trim_start().len();
cells.push(Cell::plain(&piece[..lead]));
cells.push(Cell::colored(tag, tag_color(tag)));
cells.push(Cell::plain(&piece[lead + tag.len()..]));
}
cells.retain(|cell| !cell.text.is_empty());
cells
}
/// Render the Metadata section as two aligned columns.
@@ -991,7 +1035,7 @@ fn paint_tags(value: &str, colored: bool) -> String {
/// Taken as a block rather than a line at a time because the field column cannot be
/// sized until every name has been seen. The file is untouched by this: it goes on
/// storing the markdown list, and this is only how the list is shown.
fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> String {
fn metadata_cells(lines: &[&str], colored: bool, campaign: &[Cell]) -> Vec<Cell> {
// The heading already emits its own blank separator, so the one the template
// puts under it would otherwise open the section with a gap.
let start = lines
@@ -1012,21 +1056,23 @@ fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> Strin
.max()
.unwrap_or(0);
let mut result = String::new();
let mut result = Vec::new();
for row in &rows {
match row {
MetadataRow::Field { name, value } => {
result.push_str(&paint(name, Color::Red, colored));
result.push_str(&" ".repeat(field_width - name.chars().count()));
result.push_str(COLUMN_GUTTER);
result.push_str(&metadata_value_cell(name, value, colored, campaign));
result.push(Cell::colored(*name, Color::Red));
result.push(Cell::plain(format!(
"{}{}",
" ".repeat(field_width - name.chars().count()),
COLUMN_GUTTER
)));
result.extend(metadata_value_cells(name, value, campaign));
}
// The decision this row is rendered under, not the one the terminal
// would give: `colorize_line` asked `should_use_colors()` here, which is
// how escapes reached the board's detail view.
MetadataRow::Other(text) => result.push_str(&colorize_inline(text, colored)),
// `colored` reaches only this row, and only for the markers: a hand-written
// line is the one thing in the section that can carry inline markup.
MetadataRow::Other(text) => result.extend(inline_cells(text, colored)),
}
result.push('\n');
result.push(Cell::plain("\n"));
}
result
@@ -1059,26 +1105,27 @@ pub fn is_unknown_value(value: &str) -> bool {
trimmed == NONE || trimmed == NOT_SET
}
/// Replace `**bold**` with colour and paint `[text](url)`, or leave the line exactly
/// as it is.
/// `**bold**` and `[text](url)` split into their own cells, or the line as one cell.
///
/// Taking `enabled` rather than asking makes both paths testable, and the
/// disabled path matters: stripping the markers when there is no colour to
/// replace them with loses the emphasis altogether, which is what happens to
/// every piped `show` and to everything the opencode tools read.
/// `enabled` is the only place in the body where the renderer's colour still changes
/// the layout, and it is why [`content_parts`] still takes the flag. The bold pair
/// gives its markers up to the colour that replaces them, so a renderer with none has
/// to keep them: stripping them there loses the emphasis rather than moving it, which
/// is what a piped `show` and everything the opencode tools read would get.
///
/// One walk for both markers rather than two passes. A pass over the output of
/// another would be scanning text that already holds escape sequences, and `\x1b[36m`
/// carries an opening bracket: a link scan run afterwards would take the escape for
/// markup. Walking the source once is the only place either marker can be recognised
/// for what it is.
fn colorize_inline(line: &str, enabled: bool) -> String {
fn inline_cells(line: &str, enabled: bool) -> Vec<Cell> {
if !enabled {
return line.to_string();
return vec![Cell::plain(line)];
}
let chars: Vec<char> = line.chars().collect();
let mut result = String::new();
let mut cells: Vec<Cell> = Vec::new();
let mut plain = String::new();
let mut i = 0;
while i < chars.len() {
@@ -1088,10 +1135,11 @@ fn colorize_inline(line: &str, enabled: bool) -> String {
if is_delimiter(&chars, i)
&& let Some(close) = (i + 2..chars.len()).find(|&at| is_delimiter(&chars, at))
{
let bold: String = chars[i + 2..close].iter().collect();
// `enabled`, not `should_use_colors()`. Asking again here made the
// flag a lie: the early return above respected it and this did not.
result.push_str(&paint(&bold, Color::Magenta, enabled));
flush(&mut cells, &mut plain);
cells.push(Cell::colored(
chars[i + 2..close].iter().collect::<String>(),
Color::Magenta,
));
i = close + 2;
continue;
}
@@ -1102,17 +1150,26 @@ fn colorize_inline(line: &str, enabled: bool) -> String {
// Markers and url kept, unlike the bold pair. The url is content: a
// reader of `show` wants to see where the link goes, and the terminal
// that would make it clickable is not something worklane can count on.
let link: String = chars[i..end].iter().collect();
result.push_str(&paint(&link, Color::Cyan, enabled));
flush(&mut cells, &mut plain);
cells.push(Cell::colored(chars[i..end].iter().collect::<String>(), Color::Cyan));
i = end;
continue;
}
result.push(chars[i]);
plain.push(chars[i]);
i += 1;
}
result
flush(&mut cells, &mut plain);
cells
}
/// The plain run built so far, closed off ahead of a coloured one. An empty run pushes
/// nothing, so a line opening on a marker does not start with an empty cell.
fn flush(cells: &mut Vec<Cell>, plain: &mut String) {
if !plain.is_empty() {
cells.push(Cell::plain(std::mem::take(plain)));
}
}
fn is_delimiter(chars: &[char], at: usize) -> bool {
@@ -2163,21 +2220,16 @@ impl RelationIndex {
}
}
/// A cross reference as it reads: the short id, then the name it points at.
/// A cross reference in cells: the short id, then the name it points at.
///
/// `_missing_` rather than a bare uuid for something the board no longer holds. The id
/// is kept either way, since it is the only thing left to go looking for. Shared by the
/// relations block and the Campaign field, so a dangling reference is spelled one way
/// wherever it is shown.
pub fn reference_cell(uuid: &str, name: Option<&str>, colored: bool) -> String {
paint_cells(&reference_cells(uuid, name), colored)
}
/// The same cross reference in cells, for a renderer that is not writing escapes.
/// is kept either way, since it is the only thing left to go looking for.
///
/// The one spelling of a reference, so the relations block and the Campaign field cannot
/// come to say a dangling one differently, and the board draws the id in the colour the
/// guideline gives it rather than dropping every colour to stay safe.
/// come to say a dangling one differently, and every renderer draws the id in the colour
/// the guideline gives it rather than dropping every colour to stay safe. There was a
/// `reference_cell` beside this that painted the cells for the CLI; the Campaign field
/// was its last caller, and it now takes the cells like everything else.
pub fn reference_cells(uuid: &str, name: Option<&str>) -> Vec<Cell> {
let mut cells = vec![
Cell::plain("("),
@@ -2322,11 +2374,11 @@ pub struct Cell {
}
impl Cell {
fn plain(text: impl Into<String>) -> Self {
pub fn plain(text: impl Into<String>) -> Self {
Cell { text: text.into(), color: None }
}
fn colored(text: impl Into<String>, color: Color) -> Self {
pub(crate) fn colored(text: impl Into<String>, color: Color) -> Self {
Cell {
text: text.into(),
color: Some(color),
@@ -2953,22 +3005,6 @@ pub fn display_ticket_items(items: &[TicketItem]) {
}
}
/// How many comments a ticket has, counted off the directory rather than read.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A missing directory is none, which is what a
/// ticket nobody has commented on has: no directory is created until the first comment.
fn count_comments(board: &Path, uuid: &str) -> usize {
let Ok(entries) = fs::read_dir(comments_dir(board, uuid)) else {
return 0;
};
entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
.count()
}
pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketItem>> {
let status_path = status_path.as_ref();
// The comments sit beside the status directories, so the board is this one's parent.
@@ -3018,10 +3054,10 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
}),
};
// The ticket's own ID field, not the filename stem: a comment directory is
// named by the uuid the file records, which is what `comment` wrote it under.
// The ticket's own ID field, not the filename stem: a history directory is
// named by the uuid the file records, which is what wrote the entries under it.
let uuid = parse_ticket_field(&content, "ID");
let comments = board.map_or(0, |board| count_comments(board, &uuid));
let comments = board.map_or(0, |board| crate::history::count_comments(board, &uuid));
Some(TicketItem {
title,
@@ -3217,6 +3253,37 @@ impl Drop for Fixture {
#[cfg(test)]
mod tests {
/// One line's inline markup as a string, the shape these tests were written
/// against. `enabled` is both the marker decision and, here, the painting one,
/// which is what it was before the cells conversion split the two.
fn colorize_inline(line: &str, enabled: bool) -> String {
paint_cells(&inline_cells(line, enabled), enabled)
}
/// One metadata value as a string, the shape these tests were written against.
fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -> String {
let campaign = match campaign.is_empty() {
true => Vec::new(),
false => vec![Cell::plain(campaign)],
};
paint_cells(&metadata_value_cells(name, value, &campaign), colored)
}
/// The metadata section as a string, the shape these tests were written against.
///
/// `metadata_cells` returns cells now, one layout for both renderers, so the CLI's
/// form is `paint_cells` over them. The campaign cell is a `&str` here because that
/// is all any of these needs: one run, already resolved.
fn render_metadata_table(lines: &[&str], colored: bool, campaign: &str) -> String {
let campaign = match campaign.is_empty() {
true => Vec::new(),
false => vec![Cell::plain(campaign)],
};
paint_cells(&metadata_cells(lines, colored, &campaign), colored)
}
use super::*;
/// The guard removes the directory when it goes out of scope, which is what makes the
@@ -3301,6 +3368,54 @@ mod tests {
assert!(colors_wanted(true, None, None));
}
/// The variable answers when no flag does, and the git user is never asked: the
/// closure returns a name that must not appear.
#[test]
fn the_variable_names_the_actor() {
let session = session_actor(Some("claude"), || Some("Ansho Rei".to_string()));
assert_eq!(entry_actor(None, session.as_deref()), "claude");
}
#[test]
fn the_flag_overrides_the_variable() {
let session = session_actor(Some("claude"), || None);
assert_eq!(entry_actor(Some("opencode"), session.as_deref()), "opencode");
}
/// With neither supplied the author is still the git user.
#[test]
fn the_git_user_is_the_fallback() {
let session = session_actor(None, || Some("Ansho Rei".to_string()));
assert_eq!(entry_actor(None, session.as_deref()), "Ansho Rei");
}
/// An empty variable counts as unset, the way `NO_COLOR` does, so a wrapper script
/// can clear an inherited one and get the git user back.
#[test]
fn an_empty_variable_reads_as_unset() {
let session = session_actor(Some(""), || Some("Ansho Rei".to_string()));
assert_eq!(entry_actor(None, session.as_deref()), "Ansho Rei");
// Whitespace is the same case: a shell that quotes a missing value writes one
let session = session_actor(Some(" "), || Some("Ansho Rei".to_string()));
assert_eq!(entry_actor(None, session.as_deref()), "Ansho Rei");
}
/// And with nothing at all, including a git that has no user configured.
#[test]
fn nothing_at_all_is_unknown() {
let session = session_actor(None, || None);
assert_eq!(entry_actor(None, session.as_deref()), UNKNOWN_ACTOR);
// An empty flag falls through rather than writing a blank author
assert_eq!(entry_actor(Some(""), None), UNKNOWN_ACTOR);
}
/// Free text, validated against nothing, the way the `chown` user is.
#[test]
fn an_actor_is_free_text() {
let session = session_actor(Some("claude-code, session 3 (opus)"), || None);
assert_eq!(entry_actor(None, session.as_deref()), "claude-code, session 3 (opus)");
}
#[test]
fn unset_values_are_dimmed_and_set_ones_are_not() {
// Both paths, now that the colour decision is a parameter: with colour off the
@@ -3672,12 +3787,13 @@ mod tests {
);
}
/// The count is a directory listing rather than a read: nothing here parses a comment,
/// The count is a directory listing rather than a read: nothing here parses an entry,
/// and the bodies are the detail view's business.
///
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
/// not counted as something somebody wrote. A ticket with no directory at all has
/// none, which is every ticket until the first comment creates one.
/// `.md` only, the filter `read_history` applies, so a stray file dropped in there is
/// not counted as something somebody wrote, and a mechanical entry is not counted
/// either: the card says how many things were said about the ticket. A ticket with no
/// directory at all has none, which is every ticket until the first entry creates one.
#[test]
fn collect_ticket_items_counts_the_comments_under_the_board() {
let board = tempfile::tempdir().unwrap();
@@ -3696,12 +3812,20 @@ mod tests {
write(talked_about);
write(quiet);
let comments = comments_dir(board.path(), talked_about);
fs::create_dir_all(&comments).unwrap();
fs::write(comments.join("20260823_120000_000000.md"), "**Comment**\n").unwrap();
fs::write(comments.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
// Not a comment, and not counted as one.
fs::write(comments.join("notes.txt"), "scratch\n").unwrap();
let history = crate::history::history_dir(board.path(), talked_about);
fs::create_dir_all(&history).unwrap();
fs::write(history.join("20260823_120000_000000_comment.md"), "**Comment**\n").unwrap();
// No kind in the name, as everything written before the kinds existed: a comment.
fs::write(history.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
// A field change is history but not something somebody said, so the card's
// counter leaves it out.
fs::write(
history.join("20260823_120002_000000_status.md"),
"**Status**\nbacklog → committed\n",
)
.unwrap();
// Not an entry at all, and not counted as one.
fs::write(history.join("notes.txt"), "scratch\n").unwrap();
let items = collect_ticket_items(&backlog).unwrap();
let counted = |uuid: &str| {
@@ -4233,6 +4357,111 @@ mod tests {
assert_eq!(rendered, "Metadata\n────────\n\nID abc\nOwner alice\n");
}
/// A body holding one of everything the renderer paints, pinned byte for byte.
///
/// The guard for extending `Cell` to the whole body, e4d0bb7: the board and the CLI
/// now share one layout, and the risk in that is the CLI's output moving to suit the
/// board. Written from what `show` printed before the conversion, so a difference is
/// a regression rather than a rewrite. Every run the guideline gives a colour is in
/// here: heading, plan number, criterion number and mark, bold, link, field name,
/// priority glyph, tag, unset value, and a hand-written line the table carries
/// through.
const EVERY_PAINTED_RUN: &str = "\
# The Title
## Description
Plain line with **bold** and a [link](http://x.test/a).
## Acceptance Criteria
- [x] First, with **bold**
- [ ] Second
## Implementation Plan
1. Step one
2. Step two
## Metadata
- **ID**: 641e3d5a-0000-0000-0000-000000000000
- **Priority**: 2
- **Tags**: bug, cli
- **Due**: _Not set_
- **Owner**: alice
- A hand-written note with **bold**
- **Status**: backlog
";
#[test]
fn show_prints_the_same_body_it_printed_before_the_cells_conversion() {
let orange = |text: &str| paint(text, Color::Orange, true);
let cyan = |text: &str| paint(text, Color::Cyan, true);
let red = |text: &str| paint(text, Color::Red, true);
let bold = |text: &str| paint(text, Color::Magenta, true);
let grey = |text: &str| paint(text, Color::Grey, true);
let expected = format!(
"{}\n───────────\n\n\nPlain line with {} and a {}.\n\n\
{}\n───────────────────\n\n\n\
{} {} First, with {}\n{} {} Second\n\n\
{}\n───────────────────\n\n\n{} Step one\n{} Step two\n\n\
{}\n────────\n\n\
{} 641e3d5a-0000-0000-0000-000000000000\n\
{} {} 2\n\
{} {}, {}\n\
{} {}\n\
{} alice\n\
- A hand-written note with {}\n\
{} backlog\n",
orange("Description"),
bold("bold"),
cyan("[link](http://x.test/a)"),
orange("Acceptance Criteria"),
cyan("1."),
grey("[x]"),
bold("bold"),
cyan("2."),
grey("[ ]"),
orange("Implementation Plan"),
cyan("1."),
cyan("2."),
orange("Metadata"),
red("ID"),
red("Priority"),
paint("●◐", Color::Red, true),
red("Tags"),
paint("bug", tag_color("bug"), true),
paint("cli", tag_color("cli"), true),
red("Due"),
grey(NOT_SET),
red("Owner"),
bold("bold"),
red("Status"),
);
assert_eq!(content_trim(EVERY_PAINTED_RUN, true, &Resolved::default()), expected);
}
/// The other half of the pin: with colour off the same body carries no escape byte
/// at all. Asserted beside the coloured form so neither can pass vacuously, the rule
/// 6d327df's guard was written under.
#[test]
fn the_same_body_with_colour_off_carries_no_escape() {
let plain = content_trim(EVERY_PAINTED_RUN, false, &Resolved::default());
assert!(!plain.contains('\x1b'), "{plain:?}");
// The markers stay, since with no colour to carry the emphasis they are the
// emphasis. That is `colorize_inline`'s disabled path, not a gap in the pin.
assert!(
plain.contains("Plain line with **bold** and a [link](http://x.test/a)."),
"{plain:?}"
);
assert!(plain.contains("1. [x] First, with **bold**"), "{plain:?}");
assert!(plain.contains("Priority ●◐ 2"), "{plain:?}");
}
#[test]
fn a_section_after_metadata_still_renders() {
let content = "# T\n\n## Metadata\n\n- **ID**: abc\n\n## Notes\n\nafter\n";
+1 -1
View File
@@ -314,7 +314,7 @@ fn check_leaves_nothing_behind() {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect();
assert_eq!(strays, Vec::<String>::new());
+1 -1
View File
@@ -77,7 +77,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect()
}
+150 -30
View File
@@ -41,6 +41,24 @@ fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
uuid
}
/// The one comment on a ticket, which every author test writes exactly one of.
fn only_comment(worklane_dir: &Path, uuid: &str) -> String {
let files: Vec<_> = fs::read_dir(worklane_dir.join("history").join(uuid))
.unwrap()
.filter_map(|e| e.ok())
.collect();
assert_eq!(files.len(), 1, "expected one comment");
fs::read_to_string(files[0].path()).unwrap()
}
/// A git config file holding nothing but a `user.name`, for the tests that need the
/// fallback to answer something known instead of whatever the machine is configured with.
fn git_config_naming(temp: &TempDir, name: &str) -> PathBuf {
let path = temp.path().join("gitconfig");
fs::write(&path, format!("[user]\n\tname = {}\n", name)).unwrap();
path
}
#[test]
fn comment_creates_file_with_valid_ticket_uuid() {
let temp = TempDir::new().unwrap();
@@ -55,9 +73,9 @@ fn comment_creates_file_with_valid_ticket_uuid() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
assert!(comments_dir.exists());
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
assert!(history_dir.exists());
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -107,8 +125,8 @@ fn comment_includes_git_user_and_body() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -131,8 +149,8 @@ fn comment_stored_in_timestamped_file() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -142,14 +160,14 @@ fn comment_stored_in_timestamped_file() {
}
#[test]
fn comment_creates_comments_directory() {
fn comment_creates_the_history_directory() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "reviewing", "Dir Test");
let comments_dir = worklane.join("comments").join(&uuid);
assert!(!comments_dir.exists());
let history_dir = worklane.join("history").join(&uuid);
assert!(!history_dir.exists());
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
@@ -158,36 +176,138 @@ fn comment_creates_comments_directory() {
.assert()
.success();
assert!(comments_dir.exists());
assert!(history_dir.exists());
}
#[test]
fn comment_uses_owner_flag_when_provided() {
fn comment_uses_actor_flag_when_provided() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Owner Test");
let uuid = create_ticket(&worklane, "backlog", "Actor Test");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
.arg("comment")
.args([&uuid, "Test comment with owner"])
.arg("-o")
.arg("TestUser")
.args([&uuid, "Test comment with actor"])
.args(["--actor", "TestUser"])
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
assert!(only_comment(&worklane, &uuid).contains("**Author**: TestUser"));
}
/// The flag it was, which named the ticket's assignee and not the writer of the entry.
/// Renamed without an alias, so the old spelling is a usage error rather than something
/// that half works.
#[test]
fn the_owner_flag_is_gone() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Gone Test");
for flag in ["--owner", "-o"] {
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.arg("comment")
.args([&uuid, "A body"])
.args([flag, "TestUser"])
.assert()
.failure();
}
assert!(
!worklane.join("history").join(&uuid).exists(),
"a comment was written despite the usage error"
);
}
/// The variable is the case an agent runs in: set once by its configuration and
/// inherited by every call, where a flag can be forgotten on the fortieth one.
#[test]
fn comment_takes_the_author_from_the_actor_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Variable Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.filter_map(|e| e.ok())
.collect();
let content = fs::read_to_string(files[0].path()).unwrap();
assert!(content.contains("**Author**: TestUser"));
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.arg("comment")
.args([&uuid, "Written by an agent"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: claude"));
}
#[test]
fn comment_falls_back_to_git_user_when_owner_omitted() {
fn the_actor_flag_overrides_the_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Override Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.arg("comment")
.args([&uuid, "Written by the other one"])
.args(["--actor", "opencode"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: opencode"));
}
/// An empty variable counts as unset, the convention `NO_COLOR` follows, so a wrapper
/// script can clear an inherited one and get the git user back.
#[test]
fn an_empty_actor_variable_falls_through_to_the_git_user() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Empty Variable Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "")
.env("GIT_CONFIG_GLOBAL", git_config_naming(&temp, "Configured User"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written by a person"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: Configured User"));
}
/// The last resort. Reached with a git that has no `user.name`, which is why the config
/// files are redirected: the machine running the suite has one.
#[test]
fn the_author_is_unknown_when_nothing_names_one() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "Unknown Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env_remove("WORKLANE_ACTOR")
.env("GIT_CONFIG_GLOBAL", temp.path().join("no-such-gitconfig"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written by nobody in particular"])
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: unknown"));
}
#[test]
fn comment_falls_back_to_git_user_when_actor_omitted() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
@@ -200,8 +320,8 @@ fn comment_falls_back_to_git_user_when_owner_omitted() {
.assert()
.success();
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -228,8 +348,8 @@ fn comments_added_back_to_back_are_both_kept() {
.success();
}
let comments_dir = worklane.join("comments").join(&uuid);
let files: Vec<_> = fs::read_dir(&comments_dir)
let history_dir = worklane.join("history").join(&uuid);
let files: Vec<_> = fs::read_dir(&history_dir)
.unwrap()
.filter_map(|e| e.ok())
.collect();
@@ -263,7 +383,7 @@ fn comment_accepts_a_body_that_begins_with_a_hyphen() {
.success();
}
let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid))
let bodies: String = fs::read_dir(worklane.join("history").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
@@ -318,7 +438,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
assert!(stderr.contains("<BODY>"), "unclear error: {stderr}");
assert!(
!worklane.join("comments").join(&uuid).exists(),
!worklane.join("history").join(&uuid).exists(),
"a comment was written despite the error"
);
@@ -328,7 +448,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
.assert()
.success();
let stored: String = fs::read_dir(worklane.join("comments").join(&uuid))
let stored: String = fs::read_dir(worklane.join("history").join(&uuid))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| fs::read_to_string(e.path()).unwrap())
+1 -1
View File
@@ -474,7 +474,7 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect();
+1 -1
View File
@@ -80,7 +80,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| {
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
})
.collect()
}
+476
View File
@@ -0,0 +1,476 @@
//! The history log: what the CLI records about a ticket besides what somebody said.
//!
//! One file rather than a few tests in each command's suite: the rules are about the log
//! and not about `mv` or `chown`, and the interesting cases are the ones where two
//! commands have to agree — every mechanical entry has the same shape, and every refusal
//! writes nothing.
use assert_cmd::Command;
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Output;
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
const UUID: &str = "475534a3-8a0d-45cb-9a97-39c251dd8e39";
fn setup_worklane(temp: &TempDir) -> PathBuf {
let worklane = temp.child(".worklane");
worklane.create_dir_all().unwrap();
for dir in ["backlog", "committed", "reviewing", "done"] {
worklane.child(dir).create_dir_all().unwrap();
}
worklane.path().to_path_buf()
}
/// A ticket with every field an entry can record a change to.
fn create_ticket(worklane: &Path, status: &str) -> String {
let filename = format!("{}_a-ticket.md", UUID);
fs::write(
worklane.join(status).join(&filename),
format!(
"# A ticket\n\
\n\
## Description\n\
Something to do.\n\
\n\
## Acceptance Criteria\n\
- [ ] Crit one\n\
- [ ] Crit two\n\
\n\
## Implementation Plan\n\
1. Step one\n\
\n\
## Metadata\n\
\n\
- **ID**: {}\n\
- **Priority**: 3\n\
- **Tags**: alpha\n\
- **Due**: 2026-09-01\n\
- **Owner**: alice\n\
- **Status**: {}\n",
UUID, status
),
)
.unwrap();
filename
}
/// Run with the actor named, so every author assertion is about the log and not about
/// the git user of whoever runs the suite.
fn run(temp: &TempDir, args: &[&str]) -> Output {
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.args(args)
.assert()
.get_output()
.clone()
}
/// Every entry on the ticket, name and content, in the order the log sorts them.
fn entries(worklane: &Path) -> Vec<(String, String)> {
let dir = worklane.join("history").join(UUID);
if !dir.exists() {
return vec![];
}
let mut found: Vec<(String, String)> = fs::read_dir(&dir)
.unwrap()
.filter_map(|entry| entry.ok())
.map(|entry| {
(
entry.file_name().into_string().unwrap(),
fs::read_to_string(entry.path()).unwrap(),
)
})
.collect();
found.sort_by(|a, b| a.0.cmp(&b.0));
found
}
/// The one entry a call wrote, with its kind checked off the filename.
fn only_entry(worklane: &Path, kind: &str) -> String {
let found = entries(worklane);
assert_eq!(found.len(), 1, "expected one entry, got {found:?}");
assert!(found[0].0.ends_with(&format!("_{kind}.md")), "was {}", found[0].0);
found[0].1.clone()
}
#[test]
fn mv_writes_a_status_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["mv", UUID, "--status", "committed"]);
let entry = only_entry(&worklane, "status");
assert!(entry.starts_with("**Status**\nbacklog → committed\n"), "{entry:?}");
assert!(entry.contains("**Author**: claude"), "{entry:?}");
}
#[test]
fn chown_writes_an_owner_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["chown", "bob", UUID]);
let entry = only_entry(&worklane, "owner");
assert!(entry.starts_with("**Owner**\nalice → bob\n"), "{entry:?}");
}
/// Clearing is the same field going somewhere, so it is logged, and the value it goes to
/// is the sentinel the ticket now holds rather than a word this log invented.
#[test]
fn clearing_the_owner_writes_an_owner_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["chown", "--clear", UUID]);
let entry = only_entry(&worklane, "owner");
assert!(entry.starts_with("**Owner**\nalice → _Not set_\n"), "{entry:?}");
}
#[test]
fn set_tags_writes_a_tags_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["set", UUID, "--tags", "beta", "--tags", "gamma"]);
let entry = only_entry(&worklane, "tags");
assert!(entry.starts_with("**Tags**\nalpha → beta, gamma\n"), "{entry:?}");
}
#[test]
fn clearing_the_tags_writes_a_tags_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["set", UUID, "--clear", "tags"]);
let entry = only_entry(&worklane, "tags");
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
}
/// The entry names the campaign the way a reader knows it, the codename, not the uuid
/// the field actually holds. A ticket never assigned starts from the sentinel an unset
/// field reads as everywhere else.
#[test]
fn assign_writes_a_campaign_entry_naming_the_codename() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First public release",
"--codename",
"v1",
],
);
run(&temp, &["assign", "v1", UUID]);
let entry = only_entry(&worklane, "campaign");
assert!(entry.starts_with("**Campaign**\n_Not set_ → v1\n"), "{entry:?}");
}
/// A campaign filed without a codename is recorded by its title, the name `show` and
/// `campaign ls` fall back to.
#[test]
fn a_campaign_without_a_codename_is_recorded_by_its_title() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["campaign", "add", "--title", "First public release"]);
run(&temp, &["assign", "First public", UUID]);
let entry = only_entry(&worklane, "campaign");
assert!(
entry.starts_with("**Campaign**\n_Not set_ → First public release\n"),
"{entry:?}"
);
}
/// A ticket leaving one campaign for another records both ends, which is the move the
/// log exists to answer for: the field is rewritten, so nothing else remembers where the
/// ticket was.
#[test]
fn moving_between_campaigns_records_both_names() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(
&temp,
&[
"campaign",
"add",
"--title",
"Second release",
"--codename",
"beaver",
],
);
run(&temp, &["assign", "v1", UUID]);
run(&temp, &["assign", "beaver", UUID]);
let found = entries(&worklane);
assert_eq!(found.len(), 2, "{found:?}");
assert!(found[1].1.starts_with("**Campaign**\nv1 → beaver\n"), "{:?}", found[1].1);
}
/// Assigning the campaign a ticket already names is reported as no change, and a log of
/// no change would be a log of nothing happening.
#[test]
fn a_no_op_assign_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(&temp, &["assign", "v1", UUID]);
let out = run(&temp, &["assign", "v1", UUID]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert_eq!(
entries(&worklane).len(),
1,
"a no-op assign logged a change it did not make"
);
}
/// The fields that change often enough that a log of them is noise. `set` writing one of
/// them is not an entry, and neither is a criterion being ticked.
#[test]
fn the_edits_that_are_not_logged_write_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
for args in [
vec!["set", UUID, "--title", "A better title"],
vec!["set", UUID, "--due", "2026-10-01"],
vec!["set", UUID, "--priority", "1"],
vec!["set", UUID, "--description", "Rewritten."],
vec!["set", UUID, "--plan", "One step"],
vec!["check", UUID, "1"],
vec!["uncheck", UUID, "1"],
vec!["append", UUID, "--description", "One more paragraph."],
vec!["comment", UUID, "-", "--"],
] {
let out = run(&temp, &args);
assert!(
out.status.success(),
"{args:?}: {:?}",
String::from_utf8_lossy(&out.stderr)
);
}
// The comment is the exception: it is an entry, and the only one this run wrote.
let found = entries(&worklane);
assert_eq!(found.len(), 1, "{found:?}");
assert!(found[0].0.ends_with("_comment.md"), "was {}", found[0].0);
}
/// An edit reported as no change writes no entry: the field is already what the call
/// asked for, and a log of that would be a log of nothing happening.
#[test]
fn a_no_op_edit_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
for args in [
vec!["mv", UUID, "--status", "backlog"],
vec!["chown", "alice", UUID],
vec!["set", UUID, "--tags", "alpha"],
] {
let out = run(&temp, &args);
assert!(
out.status.success(),
"{args:?}: {:?}",
String::from_utf8_lossy(&out.stderr)
);
assert_eq!(entries(&worklane), vec![], "{args:?} logged a change it did not make");
}
}
/// A refused move is not a move. The entry is written after the edit for exactly this.
#[test]
fn a_refused_move_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "reviewing");
let backward = run(&temp, &["mv", UUID, "--status", "backlog"]);
assert_eq!(backward.status.code(), Some(1));
let skipped = run(&temp, &["mv", UUID, "--status", "backlog", "-f"]);
assert!(skipped.status.success(), "{:?}", String::from_utf8_lossy(&skipped.stderr));
// The forced one moved, so it is logged; the refused one is not.
let found = entries(&worklane);
assert_eq!(found.len(), 1, "{found:?}");
assert!(found[0].1.contains("reviewing → backlog"), "{:?}", found[0].1);
}
/// A failed edit logs nothing, whatever the failure. This ticket has no Owner field, so
/// `chown` refuses it after resolving it and before writing anything.
#[test]
fn a_failed_edit_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
fs::write(
worklane.join("backlog").join(format!("{}_bare.md", UUID)),
format!("# Bare\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", UUID),
)
.unwrap();
let out = run(&temp, &["chown", "bob", UUID]);
assert_eq!(out.status.code(), Some(1));
assert_eq!(entries(&worklane), vec![], "a refused chown was logged");
}
/// One sequence, oldest first, with a comment rendered as it always was and a field
/// change as one line.
#[test]
fn show_prints_the_comments_and_the_changes_in_one_sequence() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["comment", UUID, "Picked this up."]);
run(&temp, &["mv", UUID, "--status", "committed"]);
run(&temp, &["chown", "bob", UUID]);
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
assert!(stdout.contains("HISTORY"), "{stdout}");
let said = stdout.find("Picked this up.").expect("the comment is missing");
let moved = stdout.find("backlog → committed").expect("the move is missing");
let owned = stdout.find("alice → bob").expect("the chown is missing");
assert!(said < moved && moved < owned, "out of order:\n{stdout}");
for line in ["status backlog → committed", "owner alice → bob"] {
assert!(stdout.contains(line), "{line:?} not in:\n{stdout}");
}
assert!(stdout.contains("From claude ("), "{stdout}");
}
/// A ticket nothing has happened to says so, where it used to say there were no comments.
#[test]
fn show_says_so_when_there_is_no_history() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let out = run(&temp, &["show", UUID]);
assert!(
String::from_utf8(out.stdout)
.unwrap()
.contains("No history yet.")
);
}
/// A board written by an older version: the directory is adopted on the first access,
/// the entries in it are read as the comments they are, and nothing is rewritten.
#[test]
fn an_old_comments_directory_is_adopted() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let legacy = worklane.join("comments").join(UUID);
fs::create_dir_all(&legacy).unwrap();
let name = "20260820_143012_123456.md";
let content =
"**Comment**\nSaid long ago.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n";
fs::write(legacy.join(name), content).unwrap();
let out = run(&temp, &["show", UUID]);
let stdout = String::from_utf8(out.stdout).unwrap();
assert!(stdout.contains("Said long ago."), "{stdout}");
assert!(stdout.contains("From Ansho Rei ("), "{stdout}");
assert!(!worklane.join("comments").exists(), "the old directory survived");
let moved = worklane.join("history").join(UUID).join(name);
assert_eq!(fs::read_to_string(&moved).unwrap(), content, "the entry was rewritten");
// And a new entry lands beside it, in the order it was written.
run(&temp, &["mv", UUID, "--status", "committed"]);
let found = entries(&worklane);
assert_eq!(found.len(), 2, "{found:?}");
assert_eq!(found[0].0, name);
assert!(found[1].0.ends_with("_status.md"), "was {}", found[1].0);
}
/// The flag is spelled the same on every command that writes an entry, and it overrides
/// the variable on each of them.
#[test]
fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(
&temp,
&[
"campaign",
"add",
"--title",
"First release",
"--codename",
"v1",
],
);
run(&temp, &["comment", UUID, "By hand.", "--actor", "opencode"]);
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]);
let found = entries(&worklane);
assert_eq!(found.len(), 5, "{found:?}");
for (name, content) in found {
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
}
}