Compare commits

...
12 Commits
Author SHA1 Message Date
Ansho ReiandClaude Opus 5 b4534eb86d (a9bd6f0) Recall typed lines with up and down, kept in .wlhistory, and bump to 0.32.17
The lines typed at the command prompt are walked with up and down and kept
in .wlhistory in the board's own folder, so a recall spans runs rather than
one opening of the prompt.

One Recall per tab, parallel to Board::tabs, so the tab in view decides
which list up walks: a project's lines are the ones naming its ticket ids.
The merge tab is no board, so it keeps its lines for the run and writes no
file, the answer current_project already gives a command typed there.

The position sits on Prompt and the lines on Recall, so closing the prompt
forgets the position and not the lines. A failed write is silent and an
unreadable file is an empty recall: the line is in memory either way.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-28 12:40:21 +02:00
Ansho Rei 96cddc14ad (53ffb94) Run the command the prompt parsed, and redraw the board on what it wrote, and bump to 0.32.16
The prompt parsed a line and named what it resolved to. This is the half
that does it: the parsed command goes to the same cmd_* handler main.rs
hands it to, against the selected tab's own .worklane, with a Sink over a
buffer collecting what the handler says instead of stdout.

One dispatch table, not two. main.rs's match on Command is lifted into
`dispatch`, over the command, the start path and the sink, and both
callers go through it. A second copy in tui.rs would drift the first time
a command was added and would drift silently, since both halves go on
compiling; the match is exhaustive so a new verb cannot fall into an `_`
arm either. Only `tui` is matched outside it, in main, because the board
is that table's caller rather than an entry in it, and reached from the
prompt it is refused in those words.

Two things the board has to do that the CLI never had to. It reloads
unconditionally after a command returns rather than waiting for the
digest, so a reader does not watch their own mv take up to a poll
interval to appear, and either way, since a handler that failed part way
through has still written. And the selection is restored by uuid across
that reload: mv puts the card in another column, set --title renames its
file, and a filter can drop it out of view, so the slot is not the
ticket. Where the board cannot follow it, the notice says so and which
key shows it.

What the handler says is what the board reports, word for word. Notice
therefore holds as many lines as the command used, and notice_on_row is
the one rule for where they go: one line on the footer row where a copy's
notice has always gone, anything else as a box at the foot of the
columns. A box rather than more rows of footer, because a footer that
grew and shrank as notices came and went would reflow the columns on
every keypress. A handler that errors leaves the prompt open with the
line intact, the usual cause being an ambiguous id.

`without_escapes` in util.rs is the guard at the seam. A handler's own
output is plain because the sink is, but an error message is built with
color_text, which asks the process about its stdout and under the board
answers yes about a terminal the message is not going to; a ratatui
paragraph prints an escape rather than obeying it. That is 6d327df's
fault on a new path.

The merge tab is refused for now, resolved by index rather than by the
tab's name, which is a label two projects can share. Routing by the card
a command names is ebc5755.

Not done here, and both tracked: check with no criterion still reaches
ask_which_criterion and reads a raw-mode stdin, which is 6d37042's
criterion 4 and commented there; and check_blockers warns about a
dangling blocker with eprintln!, which reaches the alternate screen
because it never passes through dispatch's result, filed as c680e24.
2026-08-27 23:38:02 +02:00
Ansho ReiandClaude Opus 5 f16e2aba0c (3686dd6) Open a command prompt on the board with : and parse what is typed, and bump to 0.32.15
The board reads. Changing anything meant quitting it and retyping an id
that was already selected. So `:` opens a one line editor in the footer
and the line is a worklane command, spelled exactly as the shell spells
it.

This is the mode and the grammar check, not the doing. Enter tokenises
the line with split_line, prepends the binary's own name and hands the
arguments to the same Cli definition the shell reaches, so a flag added
to a command is typeable here the day it is added and no list of verbs
lives on the board to go stale. A line that resolves is named and the
prompt closes; a line that does not keeps the prompt open with the line
intact and clap's own message, cut back to what fits a row. Running it
is 53ffb94, and the notice and the `↵ check` key both say so rather than
reading like a move that happened.

The prompt owns the keyboard while it is open, the contract search_key
and picker_key already keep, and declines ctrl-c for the same reason
they do. A line that ends inside a quote never reaches clap, which is
what the splitter's Unclosed state is for. --help is caught, or clap's
page lands on the alternate screen the way an unsunk println! would.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-27 21:07:26 +02:00
Ansho ReiandClaude Opus 5 bf7d8e05d8 (54fde0b) Split a typed command line into arguments the way a shell does, and bump to 0.32.14
The command prompt reads one string and clap reads an argv, so a line has
to be tokenised before anything can parse it: `comment 1b78a24 the offset
was never passed` split on whitespace is five arguments and `comment`
takes two.

One pure function over the line and the cursor, in a module of its own
rather than in tui.rs. The rules are the shell's, because that is what
the prompt promises. Two answers a shell's own splitter does not owe
anybody come out of the same scan: what a half-typed line is still
inside, as a state to report rather than an error to raise, and which
argument the cursor is in with whether it begins one.

Nothing calls it yet. The prompt that will is 3686dd6, and the dead_code
allow on the module goes when it lands.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-27 20:13:01 +02:00
Ansho Rei 30a2b3429e Specify in skill that set overwrites and to use append when that is not desired 2026-08-27 14:11:59 +02:00
Ansho Rei 69bc2feef5 (fa5662a) Write handler output through a caller-supplied sink, and bump to 0.32.13 2026-08-27 08:13:32 +02:00
Ansho Rei 8675f22209 (21713c5) Follow the picker highlight in the draw, not only on the keypress, and bump to 0.32.12 2026-08-26 12:51:21 +02:00
Ansho Rei f183d4635a (e61619a) Stage a new ticket through write_then_replace like every other write, and bump to 0.32.11 2026-08-26 12:39:08 +02:00
Ansho Rei 668263605c (8a2abf1) Give the wrapper tools for relate, campaign, assign and tags, and bump to 0.32.10 2026-08-26 12:32:15 +02:00
Ansho Rei d0a8f9a284 (10a07b8) Filter the board to the tickets in no campaign, from the campaign picker, and bump to 0.32.9 2026-08-26 02:07:16 +02:00
Ansho Rei c3efebe9b3 (86c6d27) Say the statuses, not four, where completions.rs describes what clap emits 2026-08-26 01:17:36 +02:00
Ansho Rei e26e5893f7 (ca2a124) Add --actor-from-git beside every --actor, and bump to 0.32.8 2026-08-25 17:12:25 +02:00
17 changed files with 4610 additions and 412 deletions
+58 -12
View File
@@ -1,7 +1,7 @@
# AGENTS.md
## Project Structure
- `src/main.rs` - dispatch, the SIGPIPE reset, and the TUI event loop
- `src/main.rs` - `dispatch`, the one mapping from a parsed command to its handler, the SIGPIPE reset, and the TUI event loop
- `src/command.rs` - CLI argument definitions using clap derive
- `src/completions.rs` - the generated completion script and the fish half that asks the board
- `src/handlers.rs` - one `cmd_*` per subcommand
@@ -9,6 +9,7 @@
- `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/split.rs` - one pure function turning a typed line into arguments the way a shell does, plus what the half-typed line is still inside and where the cursor sits among them
- `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
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
@@ -85,7 +86,7 @@ and this file is for what someone changing worklane's own code needs.
- Prefer explicit `match` over `unwrap_or_default()` for clarity
- Use `unwrap_or_else(|| expr)` for lazy defaults, `unwrap_or(val)` for eager defaults
- Use `anyhow!()` with context strings that include identifying info (e.g. UUID, title) not bare values
- A command whose arguments run past a handful takes a clap `Args` struct, not an inline variant with a matching parameter list: `AddArgs`, `SetArgs`, `AppendArgs`, `CheckArgs`. `add` was nine positional parameters threaded from `main` before it became `AddArgs`, and the handler destructures the struct so the body reads the same as before
- A command whose arguments run past a handful takes a clap `Args` struct, not an inline variant with a matching parameter list: `AddArgs`, `SetArgs`, `AppendArgs`, `CheckArgs`, `MvArgs`. `add` was nine positional parameters threaded from `main` before it became `AddArgs`, and the handler destructures the struct so the body reads the same as before. `mv` was the last inline variant to carry an `--actor`, and `--actor-from-git` pushed its list past the line
### CLI Arguments
- The prose arguments carry `allow_hyphen_values`, via the `PROSE` constant in `command.rs`: `add --title`, `--description`, `--acceptance`, `--plan`, and the `comment` body. Ticket text quotes flag names constantly, and without it a criterion reading `--print is supported` is parsed as a flag and the whole ticket is refused with nothing written
@@ -277,7 +278,7 @@ and this file is for what someone changing worklane's own code needs.
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::frame_rows` takes the height because of this, and `screen_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `FRAME_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
- **The frame slot is shared between the two filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what the two are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the two frames come to behave differently in a way nobody decided
- **The frame slot is shared between the filters, not doubled.** One filter is on at a time, per `Filter`, so a tag frame is the campaign frame with its three slots filled differently: `#tag` in `tag_color` on the top border where the campaign's identity goes, how many tickets carry it on the bottom right where the standing goes, and the annotation in the prose rows. `FrameContent` is what they are told apart into, and **`frame_content` is the one place they are told apart at all** — the borders, the colour, `q board`, the page indicator, the scroll and the focus are all the campaign frame's, and a second `match` on the filter below that is how the frames come to behave differently in a way nobody decided
- **A tag frame draws the annotation, which is the payoff for declaring a tag.** Whoever is browsing a tag is deciding whether the next ticket belongs in it, and the sentence saying when the tag is appropriate is then on the screen at that moment rather than in `tags.md`, which they would have to know to open. An undeclared tag draws `NO_ANNOTATION` in grey, which is also the frame saying the word was never agreed on — the vocabulary file's own placeholder rather than the description section's, so the frame and the file say the same thing about the same tag. A tag declared with nothing said about it draws the same, since here the two have the same nothing to show; the picker's sections are where the difference is actionable
- **A tag has no id, so `y` on its frame copies the word.** A tag *is* its name, matched whole by `ls --tag`, so there are no seven characters to shorten and the `#` the border draws is not part of it — `--tag "#bug"` matches nothing. The footer says `y copy tag` there for the same reason: naming it an id would send the reader looking for a short id on a border that prints a word
- **The count on a tag frame is every column's, drawn or not**, the rule the standing holds. With the filter on, those columns *are* the tickets carrying the tag, so it counts what is below it without counting it a second way. The noun is spelled out and pluralised, because a bare number on a border says nothing about what was counted, and there is no derived state beside it: a tag is a word and not a piece of work, so there is no `[open]` to be in
@@ -296,7 +297,12 @@ and this file is for what someone changing worklane's own code needs.
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
- **`t` opens the same picker over the tags instead, and taking a tag filters every column to the cards carrying it.** Every tag the board declares or carries, matched whole and case sensitively the way `ls --tag` matches — the box completes the filter, so offering what the filter would refuse is the one bug it must not have. It opens on the tag already applied, the courtesy `c` pays a campaign-filtered board, and a board carrying no tag gets the same `Notice` a board with no campaigns gets
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
- **One picker serves both lists, and `PickerRow::key` is what keeps it one.** A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead `PickerKind` decides only which list is built and what the answer filters, and everything between the keypress and the filter runs once against the key — a campaign is keyed by its uuid and a tag by itself, both strings the tab can be filtered by. Picking either clears the other without either setter remembering to, because `select_filter` replaces one `Filter`: one field, which is the same reason the frame slot is shared
- **One picker serves both lists, and `PickerRow::key` is what keeps it one.** A second picker would have been a second keyboard, query and highlight to keep in step with the first; instead `PickerKind` decides only which list is built, and everything between the keypress and the filter runs once against the key — which since the pile arrived is a `PickerKey` enum rather than a bare string, because one of the answers filters on an *absence* and carries no string to hand back. `take_picked` reads the kind off the answer rather than off which list was open. Picking any of them clears the others without either setter remembering to, because `select_filter` replaces one `Filter`: one field, which is the same reason the frame slot is shared
- **The campaign picker opens with a row for the tickets in no campaign**, above both sections and never truncated: the pile is the one question about a board of campaigns that no single campaign answers, and on a board whose completed tail is being kept back it would be pushed off the box if it listed among them. It draws its count where a campaign row draws its standing, so picking an empty pile is seen coming; under a query it answers "no campaign" and "none" and hides like any other row. **It selects `Filter::NoCampaign`, its own variant** — `retain_campaign` compares the field to the uuid it is given, so the absence case is a different predicate beside it (`retain_no_campaign`) and not a different value in it, and a magic uuid meaning none is exactly the thing that later matches a real one. A dangling uuid is *set* wrongly and stays out of the view, as it draws `_missing_` on its card rather than nothing at all
- **The pile crosses boards where a campaign cannot, so it is pickable on the merge tab.** An unset field means the same thing in every `.worklane`, the property that lets a tag filter travel there; the count adds across boards, taken at reload off the unfiltered columns like the standings are (`Tab::no_campaign`), never per draw and never off the filtered columns, which would answer zero about themselves
- **The opening highlight still lands on the first campaign, not on the pile.** Campaigns are what this list opens for; the row sits above the list without claiming it — one step up reaches it, it holds the highlight whenever it was the row selected, and only when every campaign is hidden does it take the opening one
- **The frame speaks for the pile in its own words, because the frame question stays `is_whole()`.** Exempting one variant from either half of that rule would be a state where the selection rests on a frame that is not drawn — the one thing `Focus` exists to make unrepresentable. So the title is grey `no campaign` (no id to shorten and no mark, which keeps `~` meaning a campaign and `#` a tag), the standing corner takes the count, and the prose is one grey sentence the board owns, since no file holds words for an absence
- **`y` has nothing to copy from the pile's frame** — no id to shorten and no word a command line takes, `ls --campaign` being unable to say none — so the footer leaves the key out rather than naming it into a notice, and pressing it anyway still answers "nothing to copy"
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
- **The tag sections are declared above undeclared, and truncate neither.** The same two-section shape with the opposite reason for the second: a completed campaign is finished with, so its tail is kept back before it pushes the pickable campaigns off the box, while an undeclared tag — a word somebody typed onto a ticket that the board never agreed on — is the row a reader most wants to see. A declared tag no ticket carries stays a row too: `tags.md` is what the board intends, and the vocabulary the listing reports is the one the picker offers. `campaign` and `campaigns` would have sat one under the other here, in different sections, the day the second was invented
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
@@ -306,7 +312,8 @@ and this file is for what someone changing worklane's own code needs.
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. A tag answers by itself or by its annotation, which is a reader who cannot remember the word finding it by what it was for — case insensitive here though `--tag` is not, because matching a tag is the filter and searching for one is a reader typing. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
- **The highlight follows its row, not its row number.** `place_picker` takes a key — a uuid or a tag, whichever list is open — the same string `Tab::filter` holds for either filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted key before the lists are rebuilt and puts it back after
- **The highlight follows its row, not its row number.** `place_picker` takes a key — whichever answer `PickerRow::key` hands back, the same shape `Tab::filter` holds for any of them: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted key before the lists are rebuilt and puts it back after
- **Both ends bring the highlight into the window.** Opening aligns against the screen the dispatch hands `open_picker`, and the draw follows the highlight again through `aligned_offset` on the geometry it is actually drawing — a resize between that keypress and the frame, or a tick that put the highlight back without touching the scroll, cannot leave it below the fold until some later keypress fixes it. The stored offset is left alone, the way a column's is: what is drawn is corrected immediately and the next navigation writes the correction back
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
@@ -344,6 +351,44 @@ and this file is for what someone changing worklane's own code needs.
- Both closed footers name `/`, since the jump works with a ticket open as well: it moves the selection and the overlay follows
- Out of scope on purpose, each its own ticket once the input mode exists: `n` and `N` for the next and previous match, searching the description, tags or owner, regex, and filtering the board down to matches rather than selecting one
### The Command Prompt
- **`prompt: Option<Prompt>` is the whole mode**, the shape `search` and `detail` use: open and content cannot disagree, and closing it leaves nothing to reset. `Prompt` carries the line, the cursor as a byte offset into it, and `refused`, which is `Search::missed` with something to say
- **`Board::prompt_key` is third in the pre-dispatch**, beside `search_key` and `picker_key` and on the same contract: while a command is being typed `q` is a letter, `d` leaves the columns alone and `tab` stays out of the project tabs, and `ctrl-c` is the one key declined. It takes a `Size` for enter's sake: running a command reloads the board and then has to bring the ticket it moved back into view, which is the measurement `follow_selection` takes. Only one of the two prompts can be open at once: `:` is reachable from the action arms alone, and while either has the keyboard the other's key is a character in a line
- **`esc` and `enter` are the mode's own keys and are answered in `prompt_key`; everything else belongs to the line and goes to `Prompt::key`.** That is also what keeps the borrow straight, since closing the prompt takes the whole board and editing takes only the prompt. Left, right, home, end, backspace and `ctrl-w` behave as they do in a shell, and `ctrl-w` eats the separators behind the cursor before the word behind those, so one press at the end of `mv 1b78a24 ` takes the id. There is deliberately no `tab`: suggesting the selected ticket is 00a14e7, and until then it is a key that must not reach the tabs
- **The grammar is clap's, with nothing restated.** The line is tokenised by `split_line`, the binary's own name goes in front, and the arguments go to the same `Cli` definition the shell reaches, so a flag added to a command is typeable here the day it is added. Through `Cli::command().try_get_matches_from_mut` rather than `try_parse_from`, for what the matches give back: `command_name` walks the subcommands to name what resolved (`campaign show`, not `campaign`) instead of a `match` over every variant, which would be a second list of every verb the CLI has and one that goes stale silently
- **`refused` is cleared by an edit and not by a movement.** The message is about the line, and moving the cursor does not change the line. `Prompt::key` clears it in the three arms that write to the line
- **A line that ends inside a quote never reaches clap.** That is what `Unclosed` is for: a grammar complaint about a sentence nobody finished describes the wrong thing. Enter on an empty line, or one of nothing but separators, closes the prompt with nothing said, the way `esc` does — the bare form of the CLI opens a board and there is one on the screen
- **Enter runs it, through `main.rs`'s `dispatch` and never through a handler this file names.** That match is the one mapping from a parsed command to the function that performs it: `main` calls it with its own stdout and the working directory, `Board::run` calls it with a buffer and the selected tab's root. A second copy inside `tui.rs` would drift the first time a command was added, and it would drift *silently*, since both halves go on compiling. The match is exhaustive so a new verb cannot fall into an `_` arm and do nothing, and `main_and_the_prompt_run_one_dispatch_table` reads both files as text to pin it. Only `tui` is matched outside the table, in `main`, because the board is that table's caller rather than an entry in it; reached from the prompt it is refused in those words
- **`from_arg_matches` on the same matches gives `run` the typed values.** One parse, two readings: `command_name` walks the subcommands to name what resolved and `from_arg_matches` reconstructs the `Cli`. A `match` over every `Command` variant to get one or the other would be a second list of every verb the CLI has
- **The handler's own words are what the board reports, word for word.** Those messages are written for a person already, and a second set kept here would go stale the first time one of them changed. The sink is a buffer, so the words come back as text and the board styles them; it is plain for the same reason `Detail` holds spans, since a ratatui paragraph prints an escape rather than obeying it. An error never goes through a sink at all — `color_text` asks the *process* about its stdout, which under the board answers yes about a terminal the message is not going to — so `error_lines` runs `without_escapes` over it and puts each cause on a line of its own
- **A handler that errors leaves the prompt open with the line intact.** The usual cause is an ambiguous id, and the fix is two more characters rather than the whole line retyped from `:`. Ambiguity is an `Err` carrying the candidates, not a print and an `exit`, which is what makes it safe to reach from here at all
- **The reload after a command is unconditional, and runs whether it failed or not.** `tick` reloads on the digest, which is right for a change made in another pane and needless latency for one the board just made: the reader would watch their own `mv` take up to a poll interval to appear. Either way, because a handler that failed part way through has still written
- **The selection is restored by uuid across that reload, never by index.** `mv` puts the card in another column, `set --title` renames its file, and a filter can drop it out of view entirely, so the slot is not the ticket. `Board::reselect` has three answers: the card is in a drawn column and the selection goes to it; it is on the board but in a column the rotation is hiding, which is where `--status done` lands by default, so the notice says where it went and which key shows it; or the filter no longer holds it, which is said too, since a card vanishing from under the highlight reads as a bug in the board
- **The merge tab is refused, for now.** It is the one tab that is not a board — its cards came from several `.worklane` directories and it is none of them — so `Board::current_project` answers `None` there and the command is refused rather than landing on whichever project came first. Routing by the card a command names is ebc5755. The project is resolved by index and not by the tab's name, which is a label two projects can share: e1d79c3 is exactly that, and a write routed by name would be that bug with a file changing at the end of it
- **`Notice` holds as many lines as the command used, and `Board::notice_on_row` decides where they go.** One line with nothing else holding the row draws on the footer, where a copy's notice has always drawn. Anything else — several lines, or any answer at all while the prompt is still open on an error — draws as a box at the foot of the columns, cut to what the columns leave with the dropped count on its last row. A box rather than more rows of footer, and that is the whole reason it is an overlay: a footer that grew and shrank as notices came and went would reflow the columns on every keypress, moving every card the reader is looking at. `draw` and `draw_footer` both ask `notice_on_row`, so the two cannot come to disagree and draw the message twice or not at all
- **What a refused line shows is clap's own message with the usage block cut off**, which is also what drops the `--help` line after it. `--help` is the exception: it parses as an error of the kind that means *print this* and what it would print is a page, so it is caught and answered in a row's worth of words, or clap's help lands on the alternate screen the way an unsunk `println!` would. `--version` goes through the ordinary path, because what it prints is one line by construction. `ColorChoice::Never` on the command, so nothing that reaches the row carries an escape
- **The keys' width comes off the row before the line is windowed**, so a long command does not push them off the end; a message takes the row from the keys instead, since the reader has just been told something and `esc` and `enter` still do what they did. `prompt_window` anchors the window on the cursor's right edge, which costs the text *after* the cursor on a long line: keeping both ends needs a scroll offset in state, and the draw is where the width is known and the state is not writable
- `: command` is named in every footer state, because the key works in every one of them, and the prompt's own key is drawn as `↵ run`
### The Prompt's Recall
- **`up` and `down` walk the lines already typed, and the lines are on disk.** `.wlhistory` in the board's own folder, appended as each line is entered. It is the one file under `.worklane` the board writes rather than a command, and the only one that is not markdown, which is the cost of a recall worth having: a board is opened and closed all day, and one that emptied on quit would only help inside a single sitting
- **`Recall` is per tab, parallel to `Board::tabs`**, so the tab in view decides which list `up` walks. A project's lines are the ones naming its ticket ids, and handing another board's `mv` back on this one would offer an id that resolves to nothing there. The tabs are fixed for the run, so the two vectors cannot drift, and the same index that picks the tab picks the recall
- **The merge tab has no file.** It is the one tab that is not a board, `current_project` answers `None` there and a command typed there is refused for that reason, so there is nothing to attribute a line to. Those lines are still recalled for the run: every one of them was refused, and a refused line is the one most worth getting back. When ebc5755 routes a merge line to the board its card names, that board's file is the one to append to
- **The position is on `Prompt` and the lines are on `Recall`**, so closing the prompt forgets the position and not the lines: the next `:` opens at the end of the list again, which is where a shell opens. `pending` holds the half typed line `up` walked away from, and walking `down` past the newest entry puts it back, so leaving a command to look for an older one never costs it
- **The ends are stops, not wraps.** `up` on the oldest line leaves it up rather than cycling round to the newest, which is what a shell does with it; `down` with no walk under way does nothing, since there is nothing in front of a line still being typed and emptying the row would be a keypress that destroys work. **An empty recall does nothing at all**, and that includes leaving the line alone, or `up` on a board nobody has typed at would be a way to lose what is half written
- **The line is kept before anything can refuse it.** A refused line never reached a handler and the fix is usually two characters, which is what the walk exists to save. Consecutive duplicates are kept once, against what is already held, so the rule spans runs as well as one sitting; a blank line is no command and is not kept. Nothing is trimmed
- **A failed write is silent, and an unreadable file is an empty recall.** The line is in memory either way, so the walk works for the run on a board whose folder cannot be written, and a board with no history yet is the ordinary case rather than something to say. A notice about a history file would be about the one thing the reader did not ask for
- **`.wlhistory` is not in `digest`.** Appending to it must not read as the tree moving, or every command typed would provoke a reload of every board on top of the one `run` already does
### Splitting a Typed Line
- **`split_line` is the whole module, and it knows nothing about `Board`.** The command prompt reads one string and clap reads an argv, so `comment 1b78a24 the offset was never passed` has to be tokenised before anything can parse it: split on whitespace it is five arguments and `comment` takes two. A pure function over the line and the cursor is what makes every rule reachable from a unit test, and it is in a file of its own rather than in `tui.rs`, which is eleven thousand lines already
- **The rules are the shell's, because that is what the prompt promises**: the line is spelled there exactly as it is spelled in the shell. Runs of whitespace separate arguments, single and double quotes group one, a backslash escapes the next character *except* inside single quotes where it is a backslash, and an explicitly empty `''` is an argument that exists and is empty — which is what `--title ""` being a usage error rather than a silent clear depends on. A leading hyphen is not special here: whether `--foo` is a flag or the text of a criterion is clap's question, and `PROSE` already answers it
- **Written rather than pulled in, for the two answers a shell's own splitter does not owe anybody.** A line being typed is half finished, so an unterminated quote is a state to report and not an error to raise: `Unclosed` says which quote is open, or that the line ends on a backslash with nothing yet to escape, and the arguments up to that point are handed back anyway, because that is what a hint or a completion has to work from. And completion needs the cursor: which argument it is in counting from the verb, and whether nothing of that argument lies before it, which is the difference between completing an argument and starting one. Both fall out of the one scan and neither is reachable afterwards from the arguments alone
- **`Some("")` is an argument that has been opened and is still empty**, which is the only thing that tells `''` from nothing typed at all. The cursor's answer is taken *before* the last argument is pushed, so a cursor at the end of the line is in the argument being typed rather than one past it
- The cursor is a byte offset, because that is what the prompt's own cursor is: a `String` inserts and removes at byte indices. Past the end reads as the end and inside a multi-byte character reads as after it, so nothing panics and no caller has to clamp first
- `Unclosed::Escape` wins over an open quote, being the inner of the two, and either answer refuses the line
- The binary's own name is not among the arguments: prepending it before `Cli::try_parse_from` is the caller's, since only the caller knows what it is calling
### The Copy Key
- **`y` copies the selected card's short id, over OSC 52 written by hand.** The board is where a ticket is found and the CLI is where it is acted on, and the only thing joining them was seven characters retyped off the screen. `y` reads as yank to the readers a keyboard board is for, and was the letter left: `q`, `esc`, `enter`, `space`, `hjkl`, the arrows, `pgup`, `pgdn`, `tab`, `backtab`, `d` and `/` were taken
- **The mechanism was chosen against ssh**, which is where a board is often read. An escape sequence is the only one of the three ways that crosses the connection, since it is the terminal at the reader's end that owns the clipboard. A crate (`arboard` and its kind) wants X11 and Wayland libraries at build time, and on X11 the selection belongs to the process that set it: copy an id, quit, and the paste buffer is empty, which is precisely this flow. Shelling out to `wl-copy`, `xclip` or `pbcopy` is platform sniffing plus a process spawn, and does nothing on a machine where none of them is installed or on the far end of a connection. crossterm 0.28 is what ratatui 0.29 pins and it ships no clipboard command, and the backend types have to match whatever ratatui pins, so a newer crossterm cannot be picked up on its own
@@ -410,8 +455,9 @@ and this file is for what someone changing worklane's own code needs.
### 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
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** With `--actor-from-git` and no explicit value the git user is lifted *above* the variable rather than added beneath it — the flag says attribute this to the human, and a machine with no git user configured reads `unknown` instead of quietly attributing back to the agent. An explicit `--actor` wins outright either way. `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 halves are separate pure functions, `session_actor` (the variable alone now) and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
- **The variable half is cached in a `OnceLock` and the git user in another**, the way `should_use_colors` is: neither input can change mid-run, and the git user costs a subprocess. Two caches rather than one is the whole point: baking the git user into the session's answer would make `--actor-from-git` read whatever the run's *first* call produced, since with the variable set that call never fetched git at all. `entry_actor` takes the git user as a closure so the subprocess is not run when something ahead of it already answered
- **The two flags are refused together at parse time**, clap `conflicts_with`: both answer who the entry is attributed to, and last-wins would be a silent answer to a contradictory call. `every_actor_command_takes_actor_from_git` walks the clap definition so the pair travels together onto any command that grows an `--actor`
- 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
@@ -431,7 +477,7 @@ and this file is for what someone changing worklane's own code needs.
- **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
- **`--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. `--actor-from-git` rides beside it from its own one string, the same way. 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
@@ -454,11 +500,11 @@ and this file is for what someone changing worklane's own code needs.
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered every worklane tool the file carried, eleven at the time and twenty-one at the recheck after the wrapper caught up with the CLI. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's twenty-one `export const` lines become `worklane_add` through `worklane_tags_set`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all of its tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
- **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
- **The wrapper walks clap in both directions now; until this ticket nothing did.** It was behind by four commands — `relate`, `campaign`, `assign` and `tags` had no tool, so an agent holding the tools could not reach campaigns or relations at all — and nothing compared the file to the CLI, which is how the gap opened and stayed open. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches a tool for a command that has been renamed or dropped, which fails only when an agent finally calls it; `every_subcommand_outside_the_exceptions_has_a_tool` catches the other direction, a subcommand with no tool, through the same walk off clap the completion lists take. Its exception list carries a reason per entry rather than being bare, and one of those reasons was learned from the test's first run: a bare `worklane campaign` is refused by the CLI, its subcommand required, so there is no command for a `campaign` tool to wrap and the five `campaign_*` tools are the command
- **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
Generated
+1 -1
View File
@@ -1503,7 +1503,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.32.7"
version = "0.32.17"
dependencies = [
"anyhow",
"assert_cmd",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.32.7"
version = "0.32.17"
edition = "2024"
[dependencies]
+3 -3
View File
@@ -17,7 +17,7 @@ Worklane is a local Kanban flow for agentic software development.
| `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. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
| `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; `--actor-from-git` lifts the git user over `WORKLANE_ACTOR`, for acting on the person's behalf without knowing how they spell themselves, and is refused beside `--actor` |
| `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 |
@@ -27,13 +27,13 @@ Worklane is a local Kanban flow for agentic software development.
| `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 |
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
| `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 |
| `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 twenty-one `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 |
| `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 and `--actor-from-git` lifts the git user over it per call (the two flags are refused together), 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 |
+16 -6
View File
@@ -173,10 +173,12 @@ worklane chown alice 1b78a24 # hand the ticket to someone
worklane chown --clear 1b78a24 # hand it back to nobody
```
`set` replaces, `append` adds, `--clear` empties. Neither `set` nor `append` has
`--owner` or `--status`: owner is `chown`'s and status is `mv`'s, so each field has
exactly one writer. A field set to the value it already holds is reported unchanged and
nothing is written, and so is a field cleared that was already unset.
`set` replaces, `append` adds, `--clear` empties. `set --tags` overwrites the whole
field: to add a tag to a ticket that already carries one, replace the value with every
tag separated by commas. Neither `set` nor `append` has `--owner` or `--status`: owner
is `chown`'s and status is `mv`'s, so each field has exactly one writer. A field set to
the value it already holds is reported unchanged and nothing is written, and so is a
field cleared that was already unset.
**`--clear` takes the field as its value**, one of `due`, `tags`, `priority`,
`description`, `acceptance` or `plan`, and repeats. It writes back exactly what `add`
@@ -374,12 +376,20 @@ Code, and the environment opencode is started with for opencode, since it passes
environment to the tools it runs.
**Reach for `--actor` only when the entry is somebody else's action**: the person asked
you to move a ticket, or to put words on the board as their comment, so name them on the
flag — the move was theirs and the words are theirs, and an entry carrying your name
you to move a ticket, or to put words on the board as their comment, so name them on
the flag — the move was theirs and the words are theirs, and an entry carrying your name
reads later as though you decided both. Otherwise leave it off, unless your instructions
say to use it. It is spelled the same on every command that writes an entry: `comment`,
`mv`, `chown`, `set` and `assign`.
Acting for the person without knowing how they spell themselves? `--actor-from-git`
attributes the entry to the detected git user instead of `WORKLANE_ACTOR`, so their name
is never needed. It cannot be combined with `--actor`, and a machine with no git user
configured has nobody to name: the entry reads `unknown` rather than falling back to your
variable.
```
worklane mv 1b78a24 --status done --actor "Ansho Rei"
```
worklane mv 1b78a24 --status done --actor "Ansho Rei"
```
+373
View File
@@ -497,3 +497,376 @@ function checkboxTool(verb: "check" | "uncheck") {
export const check = checkboxTool("check");
export const uncheck = checkboxTool("uncheck");
/**
* relate is the only writer of the Relations section, so the tool mirrors it rather
* than folding relations into set.
*
* The clear half is one argument per kind rather than a free-text "kind target" line,
* which is what the CLI's single --clear flag would force here. A kind inside a value
* cannot be typed by the schema, a target is a search that may itself contain spaces,
* and splitting the pair apart by hand re-parses what clap already refuses to guess at.
* Per kind the target stays a plain line, the way every other list argument works.
*/
export const relate = tool({
description:
"Record a relation from one ticket to another, or take one off. Kinds: blocked-by means this one waits on that one and its moves are refused while the target is open; regression-of means this one broke that one's fix; relates-to is a neighbour with no dependency. The edge is stored on the ticket you name alone, and show derives the other end for the target, so never record both directions.",
args: {
ticket: tool.schema
.string()
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
blocked_by: tool.schema
.string()
.describe("Target tickets this one waits on, one per line.")
.optional(),
regression_of: tool.schema
.string()
.describe("Target tickets whose fix this one broke, one per line.")
.optional(),
relates_to: tool.schema
.string()
.describe("Target tickets this one merely relates to, one per line.")
.optional(),
clear_blocked_by: tool.schema
.string()
.describe("Targets whose blocked-by edge comes off this ticket, one per line.")
.optional(),
clear_regression_of: tool.schema
.string()
.describe("Targets whose regression-of edge comes off this ticket, one per line.")
.optional(),
clear_relates_to: tool.schema
.string()
.describe("Targets whose relates-to edge comes off this ticket, one per line.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
return "Error relating tickets: ticket is required";
}
const cmd: string[] = ["relate", args.ticket];
if (args.blocked_by) itemLines(args.blocked_by).forEach((line) => cmd.push("--blocked-by", line));
if (args.regression_of) {
itemLines(args.regression_of).forEach((line) => cmd.push("--regression-of", line));
}
if (args.relates_to) itemLines(args.relates_to).forEach((line) => cmd.push("--relates-to", line));
// The kind is spelled the way the flag records it, not the way show prints it:
// the CLI takes either, and the flag spelling is the one with no space in it.
if (args.clear_blocked_by) {
itemLines(args.clear_blocked_by).forEach((line) => cmd.push("--clear", "blocked-by", line));
}
if (args.clear_regression_of) {
itemLines(args.clear_regression_of).forEach((line) => cmd.push("--clear", "regression-of", line));
}
if (args.clear_relates_to) {
itemLines(args.clear_relates_to).forEach((line) => cmd.push("--clear", "relates-to", line));
}
if (cmd.length === 2) {
return "Error relating tickets: name a relation to record or one to clear";
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error relating tickets: ${err.message}`;
}
},
});
/**
* Five tools for the five campaign subcommands, one export each.
*
* One tool taking an action argument would mirror the CLI nesting, but the schema
* could then no longer say which arguments belong to which action: campaign_set's
* force only means something beside --codename, and campaign_append's description is
* required where add's is not. Separate exports keep each schema true, and the ids
* read as the CLI path anyway, since opencode builds them from this file name plus
* the export: worklane_campaign_set.
*/
export const campaign_add = tool({
description:
"File a new campaign: several separate tickets that have to be finished together for one goal. Its state is derived from its members, so there is nothing to move or close. Give a codename when you can: one word the board draws on every card in the campaign and the shortest thing that addresses it.",
args: {
title: tool.schema
.string()
.describe("Campaign title (required)"),
description: tool.schema
.string()
.describe("What the campaign is for. Use newlines between paragraphs.")
.optional(),
codename: tool.schema
.string()
.describe("One word to call the campaign by, e.g. 'v1' or 'beaver'.")
.optional(),
owner: tool.schema
.string()
.describe("Campaign owner name. If omitted, defaults to the git user.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.title) {
return "Error adding campaign: title is required";
}
const cmd: string[] = ["campaign", "add", "--title", args.title];
if (args.description) {
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
}
if (args.codename) cmd.push("--codename", String(args.codename));
if (args.owner) cmd.push("--owner", args.owner);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error adding campaign: ${err.message}`;
}
},
});
export const campaign_set = tool({
description:
"Replace fields on an existing campaign: its title, its description or its codename. Replacing a codename the campaign already has needs force, since everything refers to the campaign by that word once it exists; setting the codename it already carries is a no-op either way. Membership is not set here, use assign.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
title: tool.schema
.string()
.describe("New title. The file is renamed to match, keeping the UUID.")
.optional(),
description: tool.schema
.string()
.describe("New description, replacing the whole section. Use newlines between paragraphs.")
.optional(),
codename: tool.schema
.string()
.describe("New codename, one word. Replacing an existing one needs force.")
.optional(),
force: tool.schema
.boolean()
.describe("Allow replacing a codename the campaign already has.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error setting campaign fields: campaign is required";
}
const cmd: string[] = ["campaign", "set", args.campaign];
if (args.title) cmd.push("--title", args.title);
if (args.description) {
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
}
if (args.codename) cmd.push("--codename", String(args.codename));
if (args.force) cmd.push("--force");
if (cmd.length === 3) {
return "Error setting campaign fields: give at least one field to change";
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error setting campaign fields: ${err.message}`;
}
},
});
export const campaign_append = tool({
description:
"Add a paragraph to a campaign's description without replacing what is already written. To replace the whole description, use campaign_set.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
description: tool.schema
.string()
.describe("Text to add as a new paragraph at the end of the description (required)."),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error appending to campaign: campaign is required";
}
if (!args.description) {
return "Error appending to campaign: description is required";
}
const cmd: string[] = ["campaign", "append", args.campaign];
descriptionLines(args.description).forEach((line: string) =>
cmd.push("--description", line),
);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error appending to campaign: ${err.message}`;
}
},
});
export const campaign_ls = tool({
description:
"List campaigns with how far each has got: id, codename or title, owner, and done members against total. Open until every member is done or discarded.",
args: {
ids: tool.schema
.boolean()
.describe("Print only id and title, tab separated, one per line, for parsing.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
const cmd = ["campaign", "ls"];
if (args.ids) cmd.push("--ids");
try {
return await run(cmd, context);
} catch (err: any) {
return `Error listing campaigns: ${err.message}, Dir: ${resolveWorklaneDir(context)}`;
}
},
});
export const campaign_show = tool({
description:
"Show a campaign's body and its members grouped by status, done included, so what is finished against what is left is one answer.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.campaign) {
return "Error showing campaign: campaign is required";
}
try {
return await run(["campaign", "show", args.campaign], context);
} catch (err: any) {
return `Error showing campaign: ${err.message}`;
}
},
});
export const assign = tool({
description:
"Put a ticket in a campaign, moving it out of whichever campaign it was in: a ticket is in at most one. Note the order, campaign first and ticket second, after chown.",
args: {
campaign: tool.schema
.string()
.describe("Campaign UUID prefix, codename or title substring (required)"),
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. 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.campaign) {
return "Error assigning ticket: campaign is required";
}
if (!args.ticket) {
return "Error assigning ticket: ticket is required";
}
const cmd: string[] = ["assign", args.campaign, args.ticket];
if (args.actor) cmd.push("--actor", args.actor);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error assigning ticket: ${err.message}`;
}
},
});
/**
* Three tools for tags, and none for `tags ls`: it prints exactly what the bare
* `worklane tags` listing prints, which the tags tool runs.
*
* The annotation lines go through descriptionLines, not itemLines: an empty value is
* a paragraph break in an annotation, exactly as it is in a description, because the
* value_parser on the CLI side accepts one and the vocabulary file stores prose under
* the tag heading.
*/
export const tags = tool({
description:
"List the tags the board carries: the tag, how many tickets carry it, and the opening line of its declared meaning. Read this before inventing a tag. Case sensitive, so bug and Bug list separately and land next to each other, which is where a near-duplicate is spotted.",
args: {},
async execute(_args: Record<string, any>, context: ToolContext) {
try {
return await run(["tags"], context);
} catch (err: any) {
return `Error listing tags: ${err.message}, Dir: ${resolveWorklaneDir(context)}`;
}
},
});
export const tags_add = tool({
description:
"Declare a tag and what it means: when the next ticket belongs in it. The tag is spelled exactly the way ls --tag matches it, one word with no comma in it.",
args: {
tag: tool.schema
.string()
.describe("The tag to declare (required), e.g. 'bug' or 'frontend'."),
annotation: tool.schema
.string()
.describe("What the tag means and when it is appropriate. Use newlines between paragraphs.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.tag) {
return "Error declaring tag: tag is required";
}
const cmd: string[] = ["tags", "add", args.tag];
if (args.annotation) {
descriptionLines(args.annotation).forEach((line: string) =>
cmd.push("--annotation", line),
);
}
try {
return await run(cmd, context);
} catch (err: any) {
return `Error declaring tag: ${err.message}`;
}
},
});
export const tags_set = tool({
description:
"Replace what a declared tag means, keeping the tickets carrying it. There is no rename: changing the word itself means rewriting the Tags field of every ticket that carries it, which is a migration and not this call.",
args: {
tag: tool.schema
.string()
.describe("The tag to change, spelled the way it was declared (required)."),
annotation: tool.schema
.string()
.describe("What the tag means, replacing whatever it said before. Use newlines between paragraphs (required)."),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.tag) {
return "Error setting tag meaning: tag is required";
}
if (!args.annotation) {
return "Error setting tag meaning: annotation is required";
}
const cmd: string[] = ["tags", "set", args.tag];
descriptionLines(args.annotation).forEach((line: string) =>
cmd.push("--annotation", line),
);
try {
return await run(cmd, context);
} catch (err: any) {
return `Error setting tag meaning: ${err.message}`;
}
},
});
+87 -20
View File
@@ -199,6 +199,13 @@ fn annotation_line(raw: &str) -> Result<String, String> {
/// 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";
/// What `--actor-from-git` says on every command that writes a history entry.
///
/// The counterpart to [`ACTOR_HELP`]: where that one names somebody specific, this one
/// says attribute it to the human whose checkout this is, without knowing how they spell
/// themselves.
const ACTOR_FROM_GIT_HELP: &str = "Attribute the entry to the detected git user instead of WORKLANE_ACTOR, for acting on the person's behalf. Cannot be combined with --actor";
/// Arguments that carry prose, and therefore have to accept a value starting with
/// a hyphen.
///
@@ -229,26 +236,7 @@ pub enum Command {
},
/// Move a ticket to a different status
Mv {
/// Ticket UUID or title
ticket: String,
/// Target status
#[arg(short, long)]
status: Status,
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
force: bool,
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
/// Why the ticket moved, recorded in the history entry beside the transition
/// it explains. Prose, so it takes a leading hyphen
#[arg(long, allow_hyphen_values = PROSE)]
reason: Option<String>,
},
Mv(MvArgs),
/// Replace fields on an existing ticket
Set(SetArgs),
@@ -298,6 +286,9 @@ pub enum Command {
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
actor_from_git: bool,
},
/// Group tickets that have to be finished together
@@ -323,6 +314,9 @@ pub enum Command {
#[arg(long, help = ACTOR_HELP)]
actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
actor_from_git: bool,
},
/// The tag vocabulary: what the board carries, and what each tag means
@@ -700,6 +694,33 @@ pub struct AddArgs {
pub priority: Option<u8>,
}
/// `mv` grew past a handful of parameters when `--actor-from-git` arrived, so it is a
/// struct like `set` and `append` rather than an inline variant.
#[derive(clap::Args)]
pub struct MvArgs {
/// Ticket UUID or title
pub ticket: String,
/// Target status
#[arg(short, long)]
pub status: Status,
/// Force move (allows backward or non-sequential moves)
#[arg(short, long)]
pub force: bool,
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
/// Why the ticket moved, recorded in the history entry beside the transition
/// it explains. Prose, so it takes a leading hyphen
#[arg(long, allow_hyphen_values = PROSE)]
pub reason: Option<String>,
}
/// `set` replaces a field outright. Owner is deliberately absent: `chown` owns that
/// field, and status is `mv`'s, so no field has two writers.
///
@@ -764,6 +785,9 @@ pub struct SetArgs {
/// command's that is logged
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
impl SetArgs {
@@ -814,6 +838,9 @@ pub struct ChownArgs {
/// change. Both are on this command because it writes both.
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
impl ChownArgs {
@@ -1015,4 +1042,44 @@ mod tests {
for two minor versions."
);
}
/// `--actor` and `--actor-from-git` are one pair that has to travel together: every
/// command that takes one takes the other, documented by the same string, because
/// the second is the first's spelling for "the human whose checkout this is".
///
/// A walker rather than five named commands, so a sixth entry-writing command fails
/// this on its own `--actor` instead of being forgotten here too.
#[test]
fn every_actor_command_takes_actor_from_git() {
let cli = Cli::command();
let mut seen = 0;
for sub in cli.get_subcommands() {
if sub.get_name() == "help" {
continue;
}
if !sub.get_arguments().any(|arg| arg.get_id().as_str() == "actor") {
continue;
}
seen += 1;
let from_git = sub
.get_arguments()
.find(|arg| arg.get_id().as_str() == "actor_from_git")
.unwrap_or_else(|| {
panic!("`{}` takes --actor but not --actor-from-git", sub.get_name())
});
assert_eq!(
from_git.get_help().map(|help| help.to_string()),
Some(ACTOR_FROM_GIT_HELP.to_string()),
"`{}` documents --actor-from-git differently",
sub.get_name()
);
}
// A guard on the walker itself: if it stopped finding commands, every assertion
// above would pass by never running.
assert_eq!(seen, 5, "expected comment, mv, chown, set and assign to carry --actor");
}
}
+6 -6
View File
@@ -11,10 +11,10 @@
//! costs one `worklane ls --ids` per keypress, which measured at 2.5ms in release on a
//! board of seventy-five tickets, comfortably below anything a person notices.
//!
//! The four statuses are half clap's: `Status` is a `ValueEnum`, so it emits them for
//! `mv --status`, but the fish generator does not emit possible values for a *positional*
//! and `ls <status>` gets nothing. Same for `completions <shell>`. So the block below
//! lists those two, from the enums rather than by hand.
//! Status values are half clap's: `Status` is a `ValueEnum`, so clap emits every one
//! of them for `mv --status`, but the fish generator does not emit possible values for
//! a *positional* and `ls <status>` gets nothing. Same for `completions <shell>`. So
//! the block below lists those two, from the enums rather than by hand.
use std::io;
@@ -231,7 +231,7 @@ complete -c worklane -n '{tag_nested}' -a '(worklane tags | cut -f1,3)'
# has a `--clear` of its own that takes a field name, and clap already offers those.
complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)'
# clap emits the four for `mv --status`, which is an option, but the fish generator
# clap emits the statuses for `mv --status`, which is an option, but the fish generator
# emits nothing for the possible values of a positional. So the one place a status is
# positional needs them listed, and the same goes for the shell below.
complete -c worklane -n '__worklane_first_arg_of ls' -a '{statuses}' -d status
@@ -616,7 +616,7 @@ mod tests {
}
}
/// The four for `mv --status` are clap's, which is half of why `Status` is a
/// The statuses for `mv --status` are clap's, which is half of why `Status` is a
/// `ValueEnum`. If clap ever stops emitting them, the fish half has to carry them
/// too, and this is what says so.
#[test]
+306 -145
View File
@@ -2,25 +2,25 @@ use anyhow::{Result, anyhow};
use chrono::Local;
use std::collections::BTreeMap;
use std::fs;
use std::io::{BufRead, IsTerminal, Write};
use std::io::{BufRead, IsTerminal};
use std::path::Path;
use crate::campaign::*;
use crate::command::{
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
ChownArgs, LsArgs, MvArgs, 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::*;
pub fn cmd_init(start: &Path) -> Result<()> {
pub fn cmd_init(start: &Path, sink: &mut Sink) -> Result<()> {
let dir = start.canonicalize().unwrap_or_else(|_| start.to_path_buf());
let worklane_dir = dir.join(".worklane");
if worklane_dir.exists() {
println!("worklane already initialized in: {}", worklane_dir.display());
sink.writeln(&format!("worklane already initialized in: {}", worklane_dir.display()))?;
return Ok(());
}
@@ -42,11 +42,11 @@ pub fn cmd_init(start: &Path) -> Result<()> {
// directory was made three lines ago, so there is nothing here to truncate.
fs::write(tags_path(&worklane_dir), TagIndex::default().render())?;
println!("Initialized worklane in: {}", worklane_dir.display());
sink.writeln(&format!("Initialized worklane in: {}", worklane_dir.display()))?;
Ok(())
}
pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path, sink: &mut Sink) -> Result<()> {
// Resolved before anything is read, so an unknown campaign is refused rather than
// silently listing nothing, and the name is available for the heading. Ahead of the
// `--ids` branch too: a completion that quietly listed the whole board because the
@@ -58,17 +58,18 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
let uuid = campaign.as_ref().map(|campaign| campaign.uuid.as_str());
let tag = args.tag.as_deref();
let priority_filter = args.priority;
let colored = sink.use_color;
if args.ids {
return list_ids(args.status, priority_filter, uuid, tag, worklane_dir);
return list_ids(sink, args.status, priority_filter, uuid, tag, worklane_dir);
}
if let Some(campaign) = &campaign {
println!(
sink.writeln(&format!(
"Members of campaign ({}) {}\n",
color_text(short_id(&campaign.uuid), Color::Red),
color_text(&campaign.title, Color::Green),
);
paint(short_id(&campaign.uuid), Color::Red, colored),
paint(&campaign.title, Color::Green, colored),
))?;
}
if let Some(status) = args.status {
@@ -92,16 +93,16 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
items.sort_by(|a, b| by_status_order(status, a, b));
if items.is_empty() {
println!("No tickets in '{}' status.", name);
sink.writeln(&format!("No tickets in '{}' status.", name))?;
return Ok(());
}
println!("Tickets in '{}' status:\n", name);
display_ticket_items(&items);
sink.writeln(&format!("Tickets in '{}' status:\n", name))?;
display_ticket_items(sink, &items)?;
} else {
// List all statuses with their ticket counts
let statuses = status_dirs();
println!("Tickets by status:\n");
sink.writeln("Tickets by status:\n")?;
for status in &statuses {
let status_path = worklane_dir.join(status);
if !status_path.exists() {
@@ -110,7 +111,7 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
let items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
let count = items.len();
let label = if count == 1 { "ticket" } else { "tickets" };
println!(" [{}] {} {}", status.to_uppercase(), count, label);
sink.writeln(&format!(" [{}] {} {}", status.to_uppercase(), count, label))?;
}
// Show all tickets except the two terminal statuses, grouped by status. Over
@@ -134,9 +135,9 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
continue;
}
let status_header =
color_text(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange);
println!("\n{}", status_header);
display_ticket_items(&items);
paint(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange, colored);
sink.writeln(&format!("\n{}", status_header))?;
display_ticket_items(sink, &items)?;
}
}
@@ -160,6 +161,7 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
/// parts company with the listing. The caller is usually a shell filling in a candidate
/// list, and an error printed over the prompt is worse there than no candidates.
fn list_ids(
sink: &mut Sink,
status: Option<Status>,
level: Option<u8>,
campaign: Option<&str>,
@@ -181,7 +183,7 @@ fn list_ids(
let mut items = filtered(collect_ticket_items(&status_path)?, level, campaign, tag);
items.sort_by(|a, b| by_status_order(status, a, b));
for item in items {
println!("{}\t{}", item.id, item.title);
sink.writeln(&format!("{}\t{}", item.id, item.title))?;
}
}
@@ -243,7 +245,7 @@ fn filter_by_priority(items: Vec<TicketItem>, level: Option<u8>) -> Vec<TicketIt
}
}
pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
pub fn cmd_add(args: &AddArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let AddArgs {
title,
description,
@@ -344,33 +346,33 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
// format allows: duplicate titles are supported and `add_allows_duplicate_titles`
// pins it. `cmd_campaign_add` deliberately does not carry it either. What is left is
// the write's own failure, named with the ticket and the path the way the other
// writes in the tree name them.
fs::write(&filepath, body).map_err(|e| {
anyhow!("Could not write ticket '{}' at {}: {}", title, filepath.display(), e)
})?;
// writes in the tree name them. Staged like them too: there is no existing content
// to corrupt, but a partial file in backlog is a ticket the listing would read, so
// the same writer as every edit is the one that makes the new file appear whole.
write_then_replace(&worklane_dir, &filepath, &filename, &body, TICKET, title)?;
println!("Created ticket: {}", filename);
sink.writeln(&format!("Created ticket: {}", filename))?;
Ok(())
}
pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
pub fn cmd_show(search: &str, worklane_dir: &Path, sink: &mut Sink) -> Result<()> {
let colored = sink.use_color;
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.
// Read before anything is printed, so a board that cannot be read fails instead of recover.
let resolved = resolved_for(&content, worklane_dir)?;
// The only title in the output: content_trim_colored used to print it a second
// The only title in the output: content_trim used to print it a second
// time from the file content. Green per the colour guideline, and the rule is
// measured in characters so a non-ASCII title is not over-drawn.
println!("{}", color_text(&title, Color::Green));
println!("{}", "─".repeat(title.chars().count()));
println!("\n{}", content_trim_colored(&content, &resolved));
sink.writeln(&paint(&title, Color::Green, colored))?;
sink.writeln(&"─".repeat(title.chars().count()))?;
sink.writeln(&format!("\n{}", content_trim(&content, colored, &resolved)))?;
if ticket_uuid != "_Not set_" {
let entries = read_history(worklane_dir, &ticket_uuid)?;
let formatted = format_history(&entries);
println!("{}", formatted);
sink.writeln(&formatted)?;
}
Ok(())
@@ -598,14 +600,15 @@ fn check_dependents(worklane_dir: &Path, uuid: &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,
actor: &Option<String>,
reason: &Option<String>,
start: &Path,
) -> Result<()> {
pub fn cmd_mv(args: &MvArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let MvArgs {
ticket: ticket_id,
status: target,
force,
actor,
actor_from_git,
reason,
} = args;
let target_status = target.as_str();
// A reason is one fact on one line, which is how the renderer draws it, so a
@@ -624,13 +627,13 @@ pub fn cmd_mv(
.iter()
.position(|status| status.as_str() == current_status)
.unwrap();
let target_idx = Status::ALL.iter().position(|status| *status == target).unwrap();
let target_idx = Status::ALL.iter().position(|status| *status == *target).unwrap();
// Discarding is not a stage of work, so the walk rules below do not apply to
// entering it: a ticket is abandoned from wherever it stands. They do apply to
// leaving it, which with discarded last in `Status::ALL` is always a backward move,
// so un-discarding needs `-f` with no rule of its own.
let discarding = target == Status::Discarded;
let discarding = *target == Status::Discarded;
if !force && !discarding && target_idx < current_idx {
return Err(anyhow!(
@@ -656,10 +659,10 @@ pub fn cmd_mv(
let recorded = parse_ticket_field(&resolved, "Status");
if recorded == target_status {
println!(
sink.writeln(&format!(
"Ticket is already in '{}' status.",
color_text(target_status, Color::Orange)
);
paint(target_status, Color::Orange, sink.use_color)
))?;
return Ok(());
}
@@ -678,12 +681,12 @@ pub fn cmd_mv(
&corrected,
)?;
println!(
sink.writeln(&format!(
"Corrected Status field on '{}': said {}, but the file sits in {}.",
color_text(&title, Color::Green),
color_text(&recorded, Color::Orange),
color_text(target_status, Color::Orange)
);
paint(&title, Color::Green, sink.use_color),
paint(&recorded, Color::Orange, sink.use_color),
paint(target_status, Color::Orange, sink.use_color)
))?;
return Ok(());
}
@@ -717,7 +720,7 @@ pub fn cmd_mv(
// crash-safe write the Status field does.
let content = set_status_stamp(
&content,
target,
*target,
&Local::now().format(TIMESTAMP_FORMAT).to_string(),
&title,
)?;
@@ -742,16 +745,16 @@ pub fn cmd_mv(
&parse_ticket_field(&resolved, "ID"),
Kind::Status,
&change(&current_status, target_status),
&resolve_actor(actor.as_deref()),
&resolve_actor(actor.as_deref(), *actor_from_git),
&reason,
)?;
println!(
sink.writeln(&format!(
"Moved ticket '{}' from {} to {}",
color_text(&title, Color::Green),
color_text(&current_status, Color::Orange),
color_text(target_status, Color::Orange),
);
paint(&title, Color::Green, sink.use_color),
paint(&current_status, Color::Orange, sink.use_color),
paint(target_status, Color::Orange, sink.use_color),
))?;
Ok(())
}
@@ -760,7 +763,9 @@ pub fn cmd_comment(
ticket_id: &str,
body: &str,
actor: &Option<String>,
actor_from_git: bool,
start: &Path,
sink: &mut Sink,
) -> Result<()> {
if body.is_empty() {
return Err(anyhow!("Comment body is required."));
@@ -779,11 +784,11 @@ pub fn cmd_comment(
&ticket_uuid,
Kind::Comment,
body,
&resolve_actor(actor.as_deref()),
&resolve_actor(actor.as_deref(), actor_from_git),
"",
)?;
println!("Comment added to '{}' ({})", title, filename);
sink.writeln(&format!("Comment added to '{}' ({})", title, filename))?;
Ok(())
}
@@ -926,8 +931,8 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static
}
}
fn report(fields: &[&str], title: &str, verb: &str) {
report_in(fields, title, Color::Green, verb)
fn report(sink: &mut Sink, fields: &[&str], title: &str, verb: &str) -> Result<()> {
report_in(sink, fields, title, Color::Green, verb)
}
/// The same, for a subject that is not a title.
@@ -937,16 +942,28 @@ fn report(fields: &[&str], title: &str, verb: &str) {
/// not one of them. The colour is passed in rather than decided here, which is the trade
/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports
/// a no-op in the same words a ticket does.
fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) {
fn report_in(
sink: &mut Sink,
fields: &[&str],
title: &str,
color: Color,
verb: &str,
) -> Result<()> {
if fields.is_empty() {
println!("No changes to '{}'", color_text(title, color));
return;
sink.writeln(&format!("No changes to '{}'", sink.color(title, color)))?;
return Ok(());
}
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color));
sink.writeln(&format!(
"{} {} on '{}'",
verb,
fields.join(", "),
sink.color(title, color)
))?;
Ok(())
}
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
pub fn cmd_set(args: &SetArgs, start: &Path, sink: &mut Sink) -> Result<()> {
if let Some(field) = args.contested() {
let name = field.name();
return Err(anyhow!(
@@ -1008,7 +1025,7 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
}
if changed.is_empty() && cleared.is_empty() {
report(&[], &title, "Updated");
report(sink, &[], &title, "Updated")?;
return Ok(());
}
@@ -1028,17 +1045,17 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
&parse_ticket_field(&original, "Tags"),
&parse_ticket_field(&content, "Tags"),
),
&resolve_actor(args.actor.as_deref()),
&resolve_actor(args.actor.as_deref(), args.actor_from_git),
"",
)?;
}
let shown = args.title.clone().unwrap_or(title);
if !changed.is_empty() {
report(&changed, &shown, "Updated");
report(sink, &changed, &shown, "Updated")?;
}
if !cleared.is_empty() {
report(&cleared, &shown, "Cleared");
report(sink, &cleared, &shown, "Cleared")?;
}
Ok(())
}
@@ -1059,7 +1076,7 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
/// for a ticket it is filing, which is a default for something new; an owner taken away
/// says nobody owns this, and putting the person running the command there instead would
/// hand them a ticket they were giving up.
pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
pub fn cmd_chown(args: &ChownArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let (ticket_id, user) = args.target().ok_or_else(|| {
anyhow!("chown takes a user and a ticket, or --clear with the ticket alone")
})?;
@@ -1071,7 +1088,7 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
let content = set_metadata_field(&original, "Owner", user.unwrap_or(NOT_SET), &title)?;
if content == original {
report(&[], &title, "Updated");
report(sink, &[], &title, "Updated")?;
return Ok(());
}
@@ -1087,7 +1104,7 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
&parse_ticket_field(&original, "Owner"),
&parse_ticket_field(&content, "Owner"),
),
&resolve_actor(args.actor.as_deref()),
&resolve_actor(args.actor.as_deref(), args.actor_from_git),
"",
)?;
@@ -1095,11 +1112,11 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
Some(_) => "Updated",
None => "Cleared",
};
report(&["owner"], &title, verb);
report(sink, &["owner"], &title, verb)?;
Ok(())
}
pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
pub fn cmd_append(args: &AppendArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(&args.ticket, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
@@ -1120,7 +1137,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
report(&changed, &title, "Appended to");
report(sink, &changed, &title, "Appended to")?;
Ok(())
}
@@ -1208,7 +1225,7 @@ fn find_relation(
}
}
pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
pub fn cmd_relate(args: &RelateArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let (status, title, original) = resolve_ticket(&args.ticket, &worklane_dir)?;
let uuid = parse_ticket_field(&original, "ID");
@@ -1301,7 +1318,7 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
}
if items.is_empty() && dropped.is_empty() {
report(&[], &title, "Recorded");
report(sink, &[], &title, "Recorded")?;
return Ok(());
}
@@ -1334,10 +1351,10 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
if !changed.is_empty() {
report(&changed, &title, "Recorded");
report(sink, &changed, &title, "Recorded")?;
}
if !cleared.is_empty() {
report(&cleared, &title, "Cleared");
report(sink, &cleared, &title, "Cleared")?;
}
Ok(())
}
@@ -1349,7 +1366,7 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
/// Written through `write_then_replace` rather than `fs::write`, so a failure leaves no
/// half-written campaign behind. `cmd_add` predates that primitive and still uses the
/// plain write; the difference is noted on the ticket rather than fixed here.
pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let CampaignAddArgs {
title,
description,
@@ -1380,7 +1397,7 @@ pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
write_then_replace(&worklane_dir, &path, &filename, &body, CAMPAIGN, title)?;
println!("Created campaign: {}", filename);
sink.writeln(&format!("Created campaign: {}", filename))?;
Ok(())
}
@@ -1390,26 +1407,26 @@ pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
/// scan per row rather than one scan reused, and it is deliberate: the alternative is a
/// map from campaign uuid to counts built in a single walk, which is worth writing when
/// a board has enough campaigns to notice and is premature now.
pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool, sink: &mut Sink) -> Result<()> {
let index = CampaignIndex::load(worklane_dir)?;
let colored = sink.use_color;
// Ahead of the empty check, which prints prose: a completion must offer nothing
// rather than offer a sentence, the same bargain `list_ids` takes with a missing
// status directory.
if ids {
for campaign in index.iter() {
println!("{}\t{}", short_id(&campaign.uuid), campaign.title);
sink.writeln(&format!("{}\t{}", short_id(&campaign.uuid), campaign.title))?;
}
return Ok(());
}
if index.is_empty() {
println!("No campaigns yet. `worklane campaign add --title` files one.");
sink.writeln("No campaigns yet. `worklane campaign add --title` files one.")?;
return Ok(());
}
let colored = should_use_colors();
println!("Campaigns:\n");
sink.writeln("Campaigns:\n")?;
for campaign in index.iter() {
let standing = Standing::of(&members(worklane_dir, &campaign.uuid)?);
@@ -1430,14 +1447,14 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
false => String::new(),
};
println!(
sink.writeln(&format!(
" ({}) {}{} | {}{}",
paint(short_id(&campaign.uuid), Color::Red, colored),
codename,
campaign.title,
standing.label(),
state,
);
))?;
}
Ok(())
@@ -1477,7 +1494,7 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
///
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
/// ago is still part of the answer to what the vocabulary has been.
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
pub fn cmd_tags(worklane_dir: &Path, sink: &mut Sink) -> Result<()> {
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
// is an error here too. The listing is the one tag command that could go on without the
// file, and reporting a vocabulary while silently treating a broken file as no file is
@@ -1505,8 +1522,8 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
for (tag, count) in counts {
match index.summary(&tag) {
Some(summary) => println!("{tag}\t{count}\t{summary}"),
None => println!("{tag}\t{count}"),
Some(summary) => sink.writeln(&format!("{tag}\t{count}\t{summary}"))?,
None => sink.writeln(&format!("{tag}\t{count}"))?,
}
}
@@ -1529,7 +1546,7 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
/// The whole file is re-rendered from the parsed vocabulary, so declaring a tag also
/// re-sorts the file and rewrites its preamble. That is why an unreadable file is an error
/// in `TagIndex::load` rather than an empty vocabulary: here, empty would mean erased.
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
@@ -1557,7 +1574,10 @@ pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
// The tag in its own colour, which is the colour it is drawn in on every card and in
// every listing: `tag_color` is a pure function of the word.
println!("Declared tag: {}", color_text(&args.tag, tag_color(&args.tag)));
sink.writeln(&format!(
"Declared tag: {}",
paint(&args.tag, tag_color(&args.tag), sink.use_color)
))?;
Ok(())
}
@@ -1575,7 +1595,7 @@ pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
/// The no-op compares the rendered file rather than the annotation, which is what `apply`
/// does for a ticket: the file is the thing that would be written, so it is the thing worth
/// asking whether the write would change.
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let mut index = TagIndex::load(&worklane_dir)?;
@@ -1604,7 +1624,7 @@ pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
)?;
}
report_in(&changed, &args.tag, tag_color(&args.tag), "Updated");
report_in(sink, &changed, &args.tag, tag_color(&args.tag), "Updated")?;
Ok(())
}
@@ -1647,7 +1667,7 @@ pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
/// the heading, so an insertion path here would be reachable only from a hand-edited file:
/// that is the opposite of the Relations case, where `add` writes nothing and the insertion
/// is the only path there is.
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
let title = campaign.title.clone();
@@ -1691,14 +1711,14 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
}
if changed.is_empty() {
report(&[], &title, "Updated");
report(sink, &[], &title, "Updated")?;
return Ok(());
}
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
save_campaign(&worklane_dir, &campaign.uuid, &title, renamed, &content)?;
report(&changed, args.title.as_ref().unwrap_or(&title), "Updated");
report(sink, &changed, args.title.as_ref().unwrap_or(&title), "Updated")?;
Ok(())
}
@@ -1715,7 +1735,7 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
///
/// One section, so there is no loop and no list to report: what changed is the description
/// or the call failed.
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> {
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
@@ -1724,7 +1744,7 @@ pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()
save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?;
report(&[DESCRIPTION.label], &campaign.title, "Appended to");
report(sink, &[DESCRIPTION.label], &campaign.title, "Appended to")?;
Ok(())
}
@@ -1733,28 +1753,35 @@ pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
/// listing. A campaign's whole point is what is finished against what is left, so
/// hiding the finished half would hide the answer.
pub fn cmd_campaign_show(search: &str, worklane_dir: &Path) -> Result<()> {
pub fn cmd_campaign_show(search: &str, worklane_dir: &Path, sink: &mut Sink) -> Result<()> {
let colored = sink.use_color;
let campaign = resolve_campaign(search, worklane_dir)?;
println!("{}", color_text(&campaign.title, Color::Green));
println!("{}", "─".repeat(campaign.title.chars().count()));
sink.writeln(&paint(&campaign.title, Color::Green, colored))?;
sink.writeln(&"─".repeat(campaign.title.chars().count()))?;
// No relations and no campaign of its own: a campaign is not a ticket, and neither
// belongs to one.
println!("\n{}", content_trim_colored(&campaign.content, &Resolved::default()));
sink.writeln(&format!(
"\n{}",
content_trim(&campaign.content, colored, &Resolved::default())
))?;
let grouped = members(worklane_dir, &campaign.uuid)?;
let standing = Standing::of(&grouped);
println!("{}", color_text("Members", Color::Orange));
println!("{}", "─".repeat("Members".chars().count()));
println!("\n{}", standing.label());
sink.writeln(&paint("Members", Color::Orange, colored))?;
sink.writeln(&"─".repeat("Members".chars().count()))?;
sink.writeln(&format!("\n{}", standing.label()))?;
for (status, items) in &grouped {
if items.is_empty() {
continue;
}
println!("\n{}", color_text(&format!("[{}]", status.to_uppercase()), Color::Orange));
display_ticket_items(items);
sink.writeln(&format!(
"\n{}",
paint(&format!("[{}]", status.to_uppercase()), Color::Orange, colored)
))?;
display_ticket_items(sink, items)?;
}
Ok(())
@@ -1772,7 +1799,9 @@ pub fn cmd_assign(
campaign_search: &str,
ticket_id: &str,
actor: &Option<String>,
actor_from_git: bool,
start: &Path,
sink: &mut Sink,
) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let campaign = resolve_campaign(campaign_search, &worklane_dir)?;
@@ -1783,11 +1812,11 @@ pub fn cmd_assign(
set_or_insert_metadata_field(&original, CAMPAIGN_FIELD, &campaign.uuid, TICKET, &title)?;
if content == original {
println!(
sink.writeln(&format!(
"Ticket '{}' is already in campaign '{}'",
color_text(&title, Color::Green),
paint(&title, Color::Green, sink.use_color),
campaign.title,
);
))?;
return Ok(());
}
@@ -1810,15 +1839,15 @@ pub fn cmd_assign(
&uuid,
Kind::Campaign,
&change(&before, campaign.name()),
&resolve_actor(actor.as_deref()),
&resolve_actor(actor.as_deref(), actor_from_git),
"",
)?;
println!(
sink.writeln(&format!(
"Assigned '{}' to campaign '{}'",
color_text(&title, Color::Green),
paint(&title, Color::Green, sink.use_color),
campaign.title,
);
))?;
Ok(())
}
@@ -1829,7 +1858,7 @@ pub fn cmd_assign(
/// reason: the opencode wrapper throws on the exit code and keeps stderr, so a list
/// printed to stdout would be discarded and an agent would learn nothing. Prompting
/// regardless would leave it blocked on a stdin that never closes.
fn ask_which_criterion(criteria: &[Criterion], title: &str) -> Result<usize> {
fn ask_which_criterion(sink: &mut Sink, criteria: &[Criterion], title: &str) -> Result<usize> {
let listing = criteria_list(criteria);
if !std::io::stdin().is_terminal() {
@@ -1840,11 +1869,14 @@ fn ask_which_criterion(criteria: &[Criterion], title: &str) -> Result<usize> {
));
}
println!("Acceptance criteria of '{}':", color_text(title, Color::Green));
println!("{}", listing);
sink.writeln(&format!(
"Acceptance criteria of '{}':",
paint(title, Color::Green, sink.use_color)
))?;
sink.writeln(&listing)?;
// Either form, since find_criteria takes both.
print!("Number or text: ");
std::io::stdout().flush()?;
sink.write("Number or text: ")?;
sink.flush()?;
let mut answer = String::new();
std::io::stdin().lock().read_line(&mut answer)?;
@@ -1930,7 +1962,7 @@ fn resolve_criteria(criteria: &[Criterion], terms: &[String], title: &str) -> Re
Ok(chosen)
}
pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path) -> Result<()> {
pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path, sink: &mut Sink) -> Result<()> {
let worklane_dir = find_worklane_dir(start)?;
let (status, title, content) = resolve_ticket(&args.ticket, &worklane_dir)?;
@@ -1940,7 +1972,7 @@ pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path) -> Result<()> {
}
let chosen = match args.criteria.as_slice() {
[] => vec![ask_which_criterion(&criteria, &title)?],
[] => vec![ask_which_criterion(sink, &criteria, &title)?],
terms => resolve_criteria(&criteria, terms, &title)?,
};
@@ -1972,7 +2004,12 @@ pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path) -> Result<()> {
past.to_string()
};
println!("{} {}: {}", state, offset + 1, color_text(&criterion.text, Color::Green));
sink.writeln(&format!(
"{} {}: {}",
state,
offset + 1,
paint(&criterion.text, Color::Green, sink.use_color)
))?;
}
Ok(())
@@ -1987,7 +2024,12 @@ pub fn cmd_check(args: &CheckArgs, checked: bool, start: &Path) -> Result<()> {
/// With no name, every shipped document is installed. Narrowing to one is the
/// exception rather than the rule, so that a document added in a later version reaches
/// anyone who already knows the command.
pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Result<()> {
pub fn cmd_install_skill(
skill: Option<&str>,
force: bool,
print: bool,
sink: &mut Sink,
) -> Result<()> {
if print {
// Printing every document would run them together into something that is not
// any of them, and the point of `--print` is to diff one against its copy.
@@ -1997,7 +2039,7 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
install::skill_names()
)
})?;
print!("{}", install::skill_named(name)?.content);
sink.write(install::skill_named(name)?.content)?;
return Ok(());
}
@@ -2007,14 +2049,14 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
};
let root = install::skills_root()?;
let written = install_each(&chosen, &root, force, |asset| {
let written = install_each(sink, &chosen, &root, force, |asset| {
format!("worklane install-skill {} --print", asset.name)
})?;
// Once, and only when something arrived: repeating it per document would make the
// instruction look like part of each outcome rather than the one thing to do next.
if written {
println!("Claude Code and opencode pick it up on their next session");
sink.writeln("Claude Code and opencode pick it up on their next session")?;
}
Ok(())
@@ -2030,6 +2072,7 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
/// each command has its own thing to say about what picks the asset up, and neither
/// should say it once per asset.
fn install_each(
sink: &mut Sink,
chosen: &[&install::Asset],
root: &Path,
force: bool,
@@ -2040,15 +2083,26 @@ fn install_each(
for asset in chosen {
match asset.install(root, force)? {
install::Outcome::Written(path) => {
println!("Installed the {} {} to: {}", asset.name, asset.what, path.display());
sink.writeln(&format!(
"Installed the {} {} to: {}",
asset.name,
asset.what,
path.display()
))?;
written = true;
}
install::Outcome::Unchanged(path) => {
println!("Already up to date: {}", path.display());
sink.writeln(&format!("Already up to date: {}", path.display()))?;
}
install::Outcome::Refused(path) => {
println!("Differs from the version in this binary: {}", path.display());
println!("Compare with `{}`, or overwrite with --force", compare(asset));
sink.writeln(&format!(
"Differs from the version in this binary: {}",
path.display()
))?;
sink.writeln(&format!(
"Compare with `{}`, or overwrite with --force",
compare(asset)
))?;
}
}
}
@@ -2061,29 +2115,136 @@ fn install_each(
/// No name argument, where `install-skill` has an optional one: there is a single tool
/// file, so a name could only be right or wrong, and `--print` needs no help deciding
/// what to print.
pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
pub fn cmd_install_tool(force: bool, print: bool, sink: &mut Sink) -> Result<()> {
if print {
print!("{}", install::TOOL.content);
sink.write(install::TOOL.content)?;
return Ok(());
}
let chosen: Vec<&install::Asset> = install::TOOLS.iter().collect();
let root = install::tools_root()?;
let written =
install_each(&chosen, &root, force, |_| "worklane install-tool --print".to_string())?;
let written = install_each(sink, &chosen, &root, force, |_| {
"worklane install-tool --print".to_string()
})?;
// Not "on its next session", which is what the skills say: opencode reads its config
// once at startup and does not reload it, so a running one keeps the tools it began
// with. The second line is there because the file is executable and looks like it
// needs a toolchain: it does not, it runs inside opencode.
if written {
println!(
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded"
);
println!(
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine"
);
sink.writeln(
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded",
)?;
sink.writeln(
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine",
)?;
}
Ok(())
}
#[cfg(test)]
mod sink_tests {
use super::*;
use crate::util::Sink;
use std::fs;
/// A throwaway board, so a test can point a handler at a sink without touching the
/// real one. Cleaned up at the end; a leftover here is an aborted test, not a
/// fixture the suite has to keep alive.
fn temp_worklane() -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("wl-sink-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&dir).unwrap();
for status in ["backlog", "committed", "reviewing", "done", "discarded"] {
fs::create_dir_all(dir.join(status)).unwrap();
}
fs::create_dir_all(dir.join("campaigns")).unwrap();
fs::write(dir.join("tags.md"), crate::tag::TagIndex::default().render()).unwrap();
dir
}
fn ticket(dir: &Path, status: &str, uuid: &str) {
fs::write(
dir.join(status).join(format!("{}_ticket.md", uuid)),
format!(
"# {u} title\n\
\n\
## Description\n\
body\n\
\n\
## Metadata\n\
\n\
- **ID**: {u}\n\
- **Priority**: 3\n\
- **Tags**: _None_\n\
- **Owner**: alice\n\
- **Created At**: 2026-08-21 02:10:17\n\
- **Status**: {status}\n",
u = uuid,
status = status,
),
)
.unwrap();
}
/// A handler writes through the sink it is handed, and a caller can read the bytes
/// back without a terminal or a real stdout.
#[test]
fn handler_writes_to_a_buffer() {
let dir = temp_worklane();
ticket(&dir, "backlog", "abc1234-def5678");
let args = LsArgs {
status: None,
priority: None,
tag: None,
campaign: None,
ids: false,
};
let mut buf = Vec::new();
{
let mut sink = Sink::buffer(&mut buf);
cmd_ls(&args, &dir, &mut sink).unwrap();
}
let out = String::from_utf8(buf).unwrap();
// The short id, not swallowed by a terminal, and no colour escapes without a
// colour sink.
assert!(out.contains("abc1234"), "ticket id missing from:\n{out}");
assert!(!out.contains('\u{1b}'), "unexpected colour in:\n{out}");
fs::remove_dir_all(&dir).ok();
}
/// The same handler behind a coloured sink paints the id red, so the colour decision
/// is the sink's and not the process's.
#[test]
fn handler_colours_when_the_sink_says_so() {
let dir = temp_worklane();
ticket(&dir, "backlog", "abc1234-def5678");
let args = LsArgs {
status: None,
priority: None,
tag: None,
campaign: None,
ids: false,
};
let mut buf = Vec::new();
{
let mut sink = Sink::new(Box::new(&mut buf), true);
// The sink is the source of the colour decision: the same word it wraps
// here is what the handler paints through `paint(.., sink.use_color)`.
assert!(sink.color("abc1234", Color::Red).contains('\u{1b}'));
cmd_ls(&args, &dir, &mut sink).unwrap();
}
let out = String::from_utf8(buf).unwrap();
assert!(out.contains("abc1234"), "ticket id missing from:\n{out}");
assert!(out.contains('\u{1b}'), "expected colour in:\n{out}");
fs::remove_dir_all(&dir).ok();
}
}
+124 -21
View File
@@ -162,7 +162,8 @@ pub fn skills_root() -> Result<PathBuf> {
/// `NO_COLOR`. Checked against opencode 1.15.10.
///
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
/// directory outside any project and registered all eleven worklane tools. The singular
/// directory outside any project and registered every worklane tool the file carried,
/// eleven at the time and twenty-one at the recheck. The singular
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
/// and `skill(s)`.
///
@@ -569,7 +570,7 @@ mod tests {
}
/// The file name is the tool id prefix, not decoration: opencode names each tool as
/// the file then the export, so a renamed file renames all eleven tools and every
/// the file then the export, so a renamed file renames all twenty-one tools and every
/// permission rule that mentions one.
#[test]
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
@@ -579,31 +580,18 @@ mod tests {
assert_eq!(TOOL.relative, "worklane.ts");
}
/// Every tool the file exports names a real subcommand.
/// Every tool the file exports names a real subcommand path.
///
/// The guard the fish completion lists already have, pointed the other way: this
/// catches a tool wrapping a command that has been renamed or dropped, which would
/// fail only when an agent finally called it. It cannot catch the reverse, a
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
/// fail only when an agent finally called it. The converse, a subcommand the wrapper
/// never grew a tool for, is [`every_subcommand_outside_the_exceptions_has_a_tool`].
#[test]
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
use clap::CommandFactory;
let commands: Vec<String> = subcommand_paths();
let exported = exported_tools();
let commands: Vec<String> = crate::Cli::command()
.get_subcommands()
.map(|command| command.get_name().to_string())
.collect();
let exported: Vec<&str> = TOOL
.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect();
assert_eq!(exported.len(), 11, "{exported:?}");
assert_eq!(exported.len(), 21, "{exported:?}");
for name in exported {
assert!(
commands.iter().any(|command| command == name),
@@ -611,4 +599,119 @@ mod tests {
);
}
}
/// The export names in the tool file: one per `export const`, which is what makes
/// them tool ids once opencode prefixes its file name.
fn exported_tools() -> Vec<&'static str> {
TOOL.content
.lines()
.filter_map(|line| line.strip_prefix("export const "))
.filter_map(|rest| rest.split_whitespace().next())
.collect()
}
/// Every subcommand as the wrapper spells it: the CLI path joined with `_`, since
/// that is how an export name has to be spelled to be an identifier. So
/// `campaign set` is `campaign_set`, and the hyphen in `install-skill` becomes one.
///
/// Walked off clap rather than written out, the way every other guard here is:
/// a hand-maintained list is the very drift this exists to catch.
fn subcommand_paths() -> Vec<String> {
use clap::CommandFactory;
fn walk(command: &clap::Command, prefix: Option<&str>, paths: &mut Vec<String>) {
for sub in command.get_subcommands() {
let name = sub.get_name();
if name == "help" {
continue;
}
let path = match prefix {
Some(prefix) => format!("{prefix}_{name}"),
None => name.to_string(),
};
let path = path.replace('-', "_");
walk(sub, Some(&path), paths);
paths.push(path);
}
}
let mut paths = Vec::new();
walk(&crate::Cli::command(), None, &mut paths);
paths
}
/// Subcommands the wrapper deliberately does not carry, each with why it is left out.
///
/// Spelled the way [`subcommand_paths`] spells a path, so a renamed command leaves a
/// stale entry behind rather than silently exempting nothing.
const NO_TOOL: [(&str, &str); 6] = [
(
"campaign",
"a bare `worklane campaign` is refused by the CLI, its subcommand is required: the five campaign_* tools are the command",
),
(
"tui",
"the board view is for a person: it takes over the terminal and returns only when quit",
),
(
"completions",
"writes a person's shell configuration, which is not an agent's call to make",
),
(
"install_skill",
"installs the skill documents themselves, so an agent running it would rewrite its own instructions mid-session",
),
(
"install_tool",
"installs this very wrapper, which opencode reads once at startup, so reinstalling from inside changes nothing until restart",
),
(
"tags_ls",
"prints exactly what the bare `worklane tags` listing prints, and the tags tool runs that",
),
];
/// The direction that went unguarded until now: every subcommand outside the
/// exception list has a tool.
///
/// This is the gap e6e3a1b taught the README about and the completion lists have
/// never had: a new subcommand reached clap, the completions and the skill, and
/// stopped there, so an agent holding the tools could not call it at all and its
/// only way to the command was to shell out, which is the thing the wrapper exists
/// to avoid. Nothing else walks the wrapper against clap, so without this test the
/// next command lands in the same silence.
#[test]
fn every_subcommand_outside_the_exceptions_has_a_tool() {
let paths = subcommand_paths();
let exported = exported_tools();
// Guard on the walker itself: if it stopped finding subcommands, both filters
// below would pass on nothing.
assert_eq!(paths.len(), 27, "{paths:?}");
assert_eq!(exported.len(), 21, "{exported:?}");
let missing: Vec<&String> = paths
.iter()
.filter(|path| !NO_TOOL.iter().any(|(name, _)| name == path))
.filter(|path| !exported.iter().any(|tool| tool == path))
.collect();
assert!(
missing.is_empty(),
"no tool for {missing:?}. A new subcommand reaches the CLI, the completions \
and the skill, and stops there: give it a tool in assets/TOOL.ts, or name \
it in NO_TOOL with why it should not have one."
);
// An exception naming a subcommand that has gone, or carrying no reason, is
// drift of exactly the kind this test is for.
for (name, reason) in NO_TOOL {
assert!(
paths.iter().any(|path| path == name),
"the exception {name:?} names no subcommand clap has"
);
assert!(!reason.trim().is_empty(), "the exception for {name} carries no reason");
}
}
}
+100 -44
View File
@@ -1,3 +1,5 @@
use std::path::Path;
use anyhow::Result;
use clap::Parser;
@@ -8,6 +10,11 @@ mod completions;
mod handlers;
mod history;
mod install;
/// The command prompt reads `split_line` and `unclosed`; `cursor_arg` and `at_new_arg` are
/// what completing an argument needs and nothing reads them yet, so the allow stays until
/// 00a14e7 and 952a9f8 land. The tests are what drive them in the meantime.
#[cfg_attr(not(test), allow(dead_code))]
mod split;
mod tag;
mod tui;
mod util;
@@ -42,77 +49,111 @@ fn main() -> Result<()> {
let start = std::env::current_dir()?;
match cli.command {
let mut sink = Sink::std();
let result = match cli.command {
// The board is the one thing `dispatch` does not run, and it is matched here
// rather than there because it is the *caller* of that table rather than an entry
// in it: a `tui` reached from the command prompt would enter the alternate screen
// a second time from inside the draw loop. `dispatch` refuses it in those words.
//
// No subcommand opens the board, the way a bare `frig` does, and with no path
// it opens the board above the working directory.
None => run_tui(&[], &start),
Some(Command::Tui { paths }) => run_tui(&paths, &start),
Some(Command::Init) => cmd_init(&start),
Some(Command::Add(args)) => cmd_add(&args, &start),
Some(Command::Ls(args)) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_ls(&args, &worklane_dir)
Some(command) => dispatch(&command, &start, &mut sink),
};
// The board (and every handler) own their own writing, so flush what the last one
// handed the sink before returning; an error path printed nothing to flush.
sink.flush()?;
result
}
/// Run one parsed command against the board at or above `start`, saying what it did
/// through `sink`.
///
/// **The one mapping from a parsed command to the function that performs it.** `main`
/// calls it with the process's stdout and the working directory; the command prompt on
/// the board calls it with a buffer and the selected tab's own root, and reads back what
/// the handler said. A second copy of this match inside `tui.rs` would be a copy that
/// drifted the first time a command was added, and it would drift *silently*, since both
/// halves would go on compiling.
///
/// A command added to [`Command`] therefore lands here once and is runnable from both.
/// The match is exhaustive for exactly that reason: there is no `_` arm for a new verb to
/// fall into and do nothing.
pub fn dispatch(command: &Command, start: &Path, sink: &mut Sink) -> Result<()> {
match command {
// Reachable only from the prompt, since `main` takes this arm before it gets
// here. A board is not something a board can open.
Command::Tui { .. } => Err(anyhow::anyhow!("`tui` opens a board, and you are on one")),
Command::Init => cmd_init(start, sink),
Command::Add(args) => cmd_add(args, start, sink),
Command::Ls(args) => {
let worklane_dir = find_worklane_dir(start)?;
cmd_ls(args, &worklane_dir, sink)
}
Some(Command::Show { id }) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_show(&id, &worklane_dir)
Command::Show { id } => {
let worklane_dir = find_worklane_dir(start)?;
cmd_show(id, &worklane_dir, sink)
}
Some(Command::Mv {
Command::Mv(args) => cmd_mv(args, start, sink),
Command::Set(args) => cmd_set(args, start, sink),
Command::Append(args) => cmd_append(args, start, sink),
Command::Relate(args) => cmd_relate(args, start, sink),
Command::Chown(args) => cmd_chown(args, start, sink),
Command::Check(args) => cmd_check(args, true, start, sink),
Command::Uncheck(args) => cmd_check(args, false, start, sink),
Command::Comment {
ticket,
status,
force,
body,
actor,
reason,
}) => cmd_mv(&ticket, status, force, &actor, &reason, &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, actor }) => {
cmd_comment(&ticket, &body, &actor, &start)
}
Some(Command::Campaign { command }) => match command {
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
actor_from_git,
} => cmd_comment(ticket, body, actor, *actor_from_git, start, sink),
Command::Campaign { command } => match command {
CampaignCommand::Add(args) => cmd_campaign_add(args, start, sink),
CampaignCommand::Ls { ids } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_ls(&worklane_dir, ids)
let worklane_dir = find_worklane_dir(start)?;
cmd_campaign_ls(&worklane_dir, *ids, sink)
}
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start),
CampaignCommand::Set(args) => cmd_campaign_set(args, start, sink),
CampaignCommand::Append(args) => cmd_campaign_append(args, start, sink),
CampaignCommand::Show { campaign } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_show(&campaign, &worklane_dir)
let worklane_dir = find_worklane_dir(start)?;
cmd_campaign_show(campaign, &worklane_dir, sink)
}
},
Some(Command::Assign { campaign, ticket, actor }) => {
cmd_assign(&campaign, &ticket, &actor, &start)
}
Command::Assign {
campaign,
ticket,
actor,
actor_from_git,
} => cmd_assign(campaign, ticket, actor, *actor_from_git, start, sink),
// 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.
Some(Command::Tags { command }) => match command {
Command::Tags { command } => match command {
None | Some(TagCommand::Ls) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir)
let worklane_dir = find_worklane_dir(start)?;
cmd_tags(&worklane_dir, sink)
}
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start),
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start),
Some(TagCommand::Add(args)) => cmd_tag_add(args, start, sink),
Some(TagCommand::Set(args)) => cmd_tag_set(args, start, sink),
},
// No board either, for the reason `install-skill` has none: a completion script
// is generated from the clap definition and is the same wherever it is run.
Some(Command::Completions { shell }) => {
completions::generate(shell, &mut std::io::stdout()).map_err(Into::into)
Command::Completions { shell } => {
completions::generate(*shell, sink.as_write()).map_err(Into::into)
}
// No board is looked for: the point of the skill is to teach an agent worklane
// before there is a `.worklane` anywhere.
Some(Command::InstallSkill { skill, force, print }) => {
cmd_install_skill(skill.as_deref(), force, print)
Command::InstallSkill { skill, force, print } => {
cmd_install_skill(skill.as_deref(), *force, *print, sink)
}
// No board either, and one agent rather than both: opencode loads the tool file,
// Claude Code has no path for one.
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print),
Command::InstallTool { force, print } => cmd_install_tool(*force, *print, sink),
}
}
@@ -208,6 +249,15 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
continue;
}
// And the command prompt, third, on the same contract: while a command is being
// typed `q` is a letter, `d` leaves the columns alone and `tab` stays out of the
// project tabs. It takes the screen because enter runs the command and then has
// to bring the ticket it moved back into view. The rule is `Board::prompt_key`,
// where a test can reach it.
if board.prompt_key(key, screen) {
continue;
}
match key.code {
// One arm, because the two keys mean one thing: close what is open, and
// quit when there is nothing left to close. Two arms carrying one rule
@@ -251,6 +301,12 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// at an open picker is taken by `picker_key` to open the picker's own
// query, so this arm is only ever the way in to the board's prompt.
KeyCode::Char('/') => board.open_search(),
// The way in to the command prompt, and the same single-shot arm `/` is:
// from the next keypress on, `prompt_key` above has the keyboard. A `:`
// typed into either open prompt is a character there and one pressed at an
// open picker is swallowed by it, so this arm is only ever the way in from
// the board itself. Free of every existing binding.
KeyCode::Char(':') => board.open_prompt(),
// `y` as in yank, for the readers this board is for, and the only letter
// left that a vim hand would reach for. The clipboard is handed in rather
// than reached for inside `Board`, so the suite can drive both answers.
+453
View File
@@ -0,0 +1,453 @@
//! Splitting a typed line into the arguments a parser wants.
//!
//! The prompt on the board takes one string and clap takes an argv, so something has to
//! turn `comment 1b78a24 the offset was never passed` into a verb, a ticket and one body
//! with spaces in it. Splitting on whitespace hands clap five arguments where `comment`
//! takes two, which is not a grammar error to report but a tokenising step nobody ran.
//!
//! The rules are the shell's, because that is what the prompt promises: a line is spelled
//! there exactly as it is spelled in the shell. Runs of whitespace separate arguments,
//! single and double quotes group one, a backslash escapes the next character except
//! inside single quotes where it is a backslash, and an explicitly empty `''` is an
//! argument that exists and is empty — which is what `--title ""` being a usage error
//! rather than a silent clear depends on. A leading hyphen is not special here: whether
//! `--foo` is a flag or the text of a criterion is clap's question, and the prose
//! arguments already accept one.
//!
//! Two things a shell's own splitter does not have to answer, and both are why this is
//! written rather than pulled in:
//!
//! - **A line being typed is half finished.** An unterminated quote is a state to report,
//! not an error to raise, because the prompt has to keep taking characters and refuse
//! only enter. See [`Unclosed`].
//! - **Completion needs to know where the cursor is.** Which argument it sits in, counting
//! from the verb, and whether nothing of that argument lies before it. Both fall out of
//! the scan for free and neither is reachable afterwards from the arguments alone.
//!
//! One pure function over the line and the cursor, and nothing here knows about `Board`.
/// What a line is still inside when it ends.
///
/// A half-typed line is not a line that failed: `comment 1b78a24 "the offset` is a
/// sentence somebody is in the middle of, and the arguments before the quote are already
/// right. So this is a state the caller reports, and the reason enter is refused while it
/// is anything but [`Unclosed::Closed`] — the arguments up to that point are still handed
/// back, because that is what a completion or a hint has to work from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Unclosed {
/// Nothing. The arguments are whole and the line can go to a parser.
Closed,
/// A `'` with no `'` after it.
Single,
/// A `"` with no `"` after it.
Double,
/// A trailing `\`, which has nothing yet to escape.
///
/// Not a quote, and reported the same way for the same reason: the character it will
/// escape is the next one typed. It wins over an open quote, being the inner of the
/// two, and either answer refuses the line.
Escape,
}
/// Which quote the scan is inside.
///
/// Private, because what a caller needs is [`Unclosed`], which also carries the state no
/// quote can. Two public spellings of one fact is how they come to disagree.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Quote {
Single,
Double,
}
/// One scan of a line: its arguments, where the cursor sits among them, and what the line
/// is still inside.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Split {
/// The arguments, in order, with the quotes and escapes taken off. The binary's own
/// name is not among them: prepending it is the caller's, since only the caller knows
/// what it is calling.
pub args: Vec<String>,
/// Which argument the cursor is in, counting from the verb at 0. Equal to
/// `args.len()` when the cursor is past the last one, which is the index an argument
/// typed next would take.
pub cursor_arg: usize,
/// Whether nothing of `cursor_arg` lies before the cursor, because the line up to it
/// ends in a separator or has nothing in it at all. That is the difference between
/// completing an argument and starting one.
pub at_new_arg: bool,
/// What the line is still inside, and therefore whether it can be run at all.
pub unclosed: Unclosed,
}
/// Split `line` into arguments, reading the cursor at `cursor` as a byte offset into it.
///
/// Bytes because that is what the prompt's own cursor is: a `String` inserts and removes
/// at byte indices. A cursor past the end of the line reads as the end, and one inside a
/// multi-byte character reads as being after that character, so neither can panic and
/// neither needs the caller to have clamped it first.
pub fn split_line(line: &str, cursor: usize) -> Split {
let mut args: Vec<String> = Vec::new();
// `Some("")` is an argument that has been opened and is still empty, which is what
// tells `''` from nothing at all: a bare `take()` cannot make that distinction.
let mut arg: Option<String> = None;
let mut quote: Option<Quote> = None;
let mut escape = false;
// The cursor's answer, taken at the character it falls on and never revised.
let mut at: Option<(usize, bool)> = None;
for (offset, c) in line.char_indices() {
if at.is_none() && offset >= cursor {
at = Some((args.len(), arg.is_none()));
}
if escape {
arg.get_or_insert_default().push(c);
escape = false;
continue;
}
match (quote, c) {
// The shell's exception, and the reason a criterion reading `a\b` survives
// being typed as `'a\b'`: single quotes are literal, backslash included.
(Some(Quote::Single), '\\') => arg.get_or_insert_default().push(c),
(_, '\\') => escape = true,
(None, '\'') => {
quote = Some(Quote::Single);
arg.get_or_insert_default();
}
(None, '"') => {
quote = Some(Quote::Double);
arg.get_or_insert_default();
}
(Some(Quote::Single), '\'') | (Some(Quote::Double), '"') => quote = None,
// A run of separators closes the open argument once and then finds none.
(None, ws) if ws.is_whitespace() => {
if let Some(done) = arg.take() {
args.push(done);
}
}
_ => arg.get_or_insert_default().push(c),
}
}
// Before the last argument is pushed, so a cursor at the end of the line is still in
// the argument it is typing rather than one past it.
let (cursor_arg, at_new_arg) = at.unwrap_or((args.len(), arg.is_none()));
if let Some(last) = arg {
args.push(last);
}
Split {
args,
cursor_arg,
at_new_arg,
unclosed: match (escape, quote) {
(true, _) => Unclosed::Escape,
(false, Some(Quote::Single)) => Unclosed::Single,
(false, Some(Quote::Double)) => Unclosed::Double,
(false, None) => Unclosed::Closed,
},
}
}
#[cfg(test)]
mod tests {
use super::*;
/// One line and everything the scan is supposed to say about it.
///
/// The defaults are the empty line's own answers, so a row states the rule it is about
/// and stays quiet about the rest.
struct Case {
line: &'static str,
/// Where the cursor is, or the end of the line, which is where it sits while a
/// line is being typed. Only the cursor rows move it.
cursor: Option<usize>,
args: &'static [&'static str],
cursor_arg: usize,
at_new_arg: bool,
unclosed: Unclosed,
}
impl Default for Case {
fn default() -> Self {
Case {
line: "",
cursor: None,
args: &[],
cursor_arg: 0,
at_new_arg: true,
unclosed: Unclosed::Closed,
}
}
}
/// Every field of every row, each named in its own failure: a table that reports only
/// the first mismatch makes the next run tell a different story than this one.
fn check(cases: &[Case]) {
for case in cases {
let cursor = case.cursor.unwrap_or(case.line.len());
let split = split_line(case.line, cursor);
let args: Vec<&str> = split.args.iter().map(String::as_str).collect();
let at = format!("{:?} with the cursor at {cursor}", case.line);
assert_eq!(args, case.args, "arguments of {at}");
assert_eq!(split.cursor_arg, case.cursor_arg, "cursor argument of {at}");
assert_eq!(split.at_new_arg, case.at_new_arg, "new argument of {at}");
assert_eq!(split.unclosed, case.unclosed, "unclosed state of {at}");
}
}
#[test]
fn a_line_splits_into_arguments_the_way_a_shell_splits_one() {
check(&[
// Nothing typed yet, which is the state the prompt opens in.
Case::default(),
Case {
line: "tags",
args: &["tags"],
at_new_arg: false,
..Case::default()
},
Case {
line: "mv 1b78a24 --status committed",
args: &["mv", "1b78a24", "--status", "committed"],
cursor_arg: 3,
at_new_arg: false,
..Case::default()
},
// Runs of separators collapse, at either end and in the middle, and a tab is
// one of them.
Case {
line: " mv 1b78a24 ",
args: &["mv", "1b78a24"],
cursor_arg: 2,
..Case::default()
},
Case {
line: "mv\t1b78a24",
args: &["mv", "1b78a24"],
cursor_arg: 1,
at_new_arg: false,
..Case::default()
},
// What the ticket for this was written about: one body, spaces and all.
Case {
line: "comment 1b78a24 \"the offset was never passed\"",
args: &["comment", "1b78a24", "the offset was never passed"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// Single quotes group the same, and a run of spaces inside one is not a
// separator to collapse.
Case {
line: "comment 1b78a24 'two spaces'",
args: &["comment", "1b78a24", "two spaces"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// A quote in the middle of an argument groups part of it, which is how a
// `--flag=value` carrying a space is typed.
Case {
line: "set 1b78a24 --title=\"a b\"",
args: &["set", "1b78a24", "--title=a b"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// A backslash escapes the next character: a separator, a quote, itself.
Case {
line: "comment 1b78a24 a\\ b",
args: &["comment", "1b78a24", "a b"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
Case {
line: "comment 1b78a24 \"she said \\\"no\\\"\"",
args: &["comment", "1b78a24", "she said \"no\""],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
Case {
line: "comment 1b78a24 a\\\\b",
args: &["comment", "1b78a24", "a\\b"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// Except inside single quotes, where it is a character like any other.
Case {
line: "comment 1b78a24 'a\\b'",
args: &["comment", "1b78a24", "a\\b"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// A leading hyphen is clap's business, not the splitter's.
Case {
line: "add --title --print is supported",
args: &["add", "--title", "--print", "is", "supported"],
cursor_arg: 4,
at_new_arg: false,
..Case::default()
},
// An empty quoted value is an argument that exists and is empty. Losing it
// here would turn a usage error into a silent clear.
Case {
line: "set 1b78a24 --title \"\"",
args: &["set", "1b78a24", "--title", ""],
cursor_arg: 3,
at_new_arg: false,
..Case::default()
},
Case {
line: "''",
args: &[""],
at_new_arg: false,
..Case::default()
},
]);
}
#[test]
fn a_half_typed_line_says_what_it_is_still_inside_and_hands_back_the_rest() {
check(&[
// The arguments before the open quote are already right, and the open one is
// as far as it has been typed.
Case {
line: "comment 1b78a24 \"the offset",
args: &["comment", "1b78a24", "the offset"],
cursor_arg: 2,
at_new_arg: false,
unclosed: Unclosed::Double,
..Case::default()
},
Case {
line: "comment 1b78a24 'the offset",
args: &["comment", "1b78a24", "the offset"],
cursor_arg: 2,
at_new_arg: false,
unclosed: Unclosed::Single,
..Case::default()
},
// A quote just opened is an argument that exists and is empty, the same shape
// a closed `''` leaves.
Case {
line: "comment 1b78a24 \"",
args: &["comment", "1b78a24", ""],
cursor_arg: 2,
at_new_arg: false,
unclosed: Unclosed::Double,
..Case::default()
},
// A trailing backslash has nothing yet to escape. It opened no argument, so
// the cursor is starting one.
Case {
line: "mv 1b78a24 \\",
args: &["mv", "1b78a24"],
cursor_arg: 2,
unclosed: Unclosed::Escape,
..Case::default()
},
// Inside a quote the escape is the inner of the two, and it is what the line
// is waiting on.
Case {
line: "comment 1b78a24 \"a\\",
args: &["comment", "1b78a24", "a"],
cursor_arg: 2,
at_new_arg: false,
unclosed: Unclosed::Escape,
..Case::default()
},
// A closed quote reopened is open again: the state is where the scan ended,
// not how many quotes were typed.
Case {
line: "comment 1b78a24 'a' 'b",
args: &["comment", "1b78a24", "a", "b"],
cursor_arg: 3,
at_new_arg: false,
unclosed: Unclosed::Single,
..Case::default()
},
]);
}
#[test]
fn the_split_says_which_argument_the_cursor_is_in_and_whether_it_begins_one() {
check(&[
// The line is split whole whatever the cursor is doing: only the two cursor
// answers move.
Case {
line: "mv 1b78a24",
cursor: Some(0),
args: &["mv", "1b78a24"],
..Case::default()
},
Case {
line: "mv 1b78a24",
cursor: Some(1),
args: &["mv", "1b78a24"],
at_new_arg: false,
..Case::default()
},
// At the end of the verb, still in the verb: the cursor is completing it.
Case {
line: "mv 1b78a24",
cursor: Some(2),
args: &["mv", "1b78a24"],
at_new_arg: false,
..Case::default()
},
// Past the separator, so the argument at 1 has nothing before the cursor even
// though the line goes on to hold one.
Case {
line: "mv 1b78a24",
cursor: Some(3),
args: &["mv", "1b78a24"],
cursor_arg: 1,
..Case::default()
},
// A cursor past the end of the line reads as the end of it.
Case {
line: "mv",
cursor: Some(99),
args: &["mv"],
at_new_arg: false,
..Case::default()
},
// Inside a quoted argument the cursor is in that argument, not in a fourth
// one the quotes might look like they opened.
Case {
line: "comment 1b78a24 \"the offset\"",
cursor: Some(20),
args: &["comment", "1b78a24", "the offset"],
cursor_arg: 2,
at_new_arg: false,
..Case::default()
},
// Byte offsets, so a multi-byte character before the cursor counts for its
// width and not for one: 8 is where `é` starts and 9 is inside it.
Case {
line: "comment é",
cursor: Some(8),
args: &["comment", "é"],
cursor_arg: 1,
..Case::default()
},
// A cursor inside a character reads as being after it, which is the answer
// that cannot claim an argument has not started when it has.
Case {
line: "comment é",
cursor: Some(9),
args: &["comment", "é"],
cursor_arg: 1,
at_new_arg: false,
..Case::default()
},
]);
}
}
+2651 -92
View File
File diff suppressed because it is too large Load Diff
+251 -61
View File
@@ -1,7 +1,7 @@
use anyhow::{Result, anyhow};
use chrono::NaiveDateTime;
use std::fs;
use std::io::IsTerminal;
use std::io::{IsTerminal, Write};
use std::path::Path;
use std::sync::OnceLock;
@@ -303,6 +303,119 @@ pub fn color_text(text: &str, color: Color) -> String {
paint(text, color, should_use_colors())
}
/// `text` with every ANSI escape sequence taken out of it.
///
/// The inverse of what [`paint`] writes, and the guard at the seam where a handler's
/// words become something the board draws: ratatui prints an escape as literal bytes
/// rather than obeying it, so a painted status reaches the screen as `\x1b[33m` and
/// the word after it.
///
/// A [`Sink`] the board owns is plain, so this is not about a handler's ordinary
/// output. It is about the strings that never go through one: an error message is
/// built with `color_text`, which asks the *process* about its stdout, and under the
/// board that answers yes about a terminal the message is not going to.
pub fn without_escapes(text: &str) -> String {
let mut out = String::with_capacity(text.len());
let mut chars = text.chars();
while let Some(c) = chars.next() {
if c != '\x1b' {
out.push(c);
continue;
}
// A CSI sequence is `\x1b[`, then parameter bytes, closed by a final byte in
// `@` to `~`. That is every sequence `Color` writes. Anything else is a short
// escape whose one following character goes with it, which `next` has taken.
if chars.next() == Some('[') {
for c in chars.by_ref() {
if ('\x40'..='\x7e').contains(&c) {
break;
}
}
}
}
out
}
/// A destination for a command's output, chosen by the caller.
///
/// `main` hands a handler its own stdout and nothing about the CLI changes; the
/// board (or a test) hands it an in-memory buffer and reads back what the command
/// said. Threading the writer and the colour decision together means every print
/// site reaches both, and a handler never asks the process about its own stdout.
///
/// `use_color` is the sink's answer, not a read of [`should_use_colors`]: a process
/// whose stdout is a pipe still wants colour when the sink is a buffer a renderer
/// will colour itself, and the board wants plain text however the terminal answers.
pub struct Sink<'a> {
writer: Box<dyn Write + 'a>,
/// Whether the bytes this sink writes carry colour escapes.
pub use_color: bool,
}
impl<'a> Sink<'a> {
/// The process's stdout, coloured by what the terminal wants.
///
/// What `main` passes, so the CLI's output is byte identical to before: every
/// command wrote to stdout through `println!`, and this sink writes to the same
/// stdout through the same [`paint`].
pub fn std() -> Sink<'static> {
// Through `new` so the process's stdout is just another writer the sink wraps.
Sink::new(Box::new(std::io::stdout()), should_use_colors())
}
/// An in-memory buffer, plain, for a test or a caller that colours the text
/// itself.
///
/// What the board's command prompt passes: the handler's words come back as text
/// and the board styles them with ratatui, which is also why it must not be handed
/// a coloured one — a paragraph prints an escape rather than obeying it.
pub fn buffer(target: &'a mut Vec<u8>) -> Sink<'a> {
Sink {
writer: Box::new(target),
use_color: false,
}
}
/// Any writer, with the colour decision given.
pub fn new(writer: Box<dyn Write + 'a>, use_color: bool) -> Sink<'a> {
Sink { writer, use_color }
}
/// The writer, for a caller that already knows how to fill it (the completions
/// generator).
pub fn as_write(&mut self) -> &mut dyn Write {
&mut *self.writer
}
/// Write `text` followed by a newline, the way `println!` did.
pub fn writeln(&mut self, text: &str) -> Result<()> {
self.writer.write_all(text.as_bytes())?;
self.writer.write_all(b"\n")?;
Ok(())
}
/// Write `text` with no terminator, the way `print!` did. The caller flushes
/// when it then waits on input.
pub fn write(&mut self, text: &str) -> Result<()> {
self.writer.write_all(text.as_bytes())?;
Ok(())
}
/// Flush the writer, so a prompt reaches the terminal before a read.
pub fn flush(&mut self) -> Result<()> {
self.writer.flush()?;
Ok(())
}
/// `text` wrapped in `color`'s escape when this sink is coloured.
pub fn color(&self, text: &str, color: Color) -> String {
paint(text, color, self.use_color)
}
}
/// What sits at a candidate `.worklane` path.
///
/// The distinction the walk turns on is between nothing there and something
@@ -449,52 +562,78 @@ 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.
/// The actor for the whole run, from the variable alone.
///
/// 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(),
}
/// `NO_COLOR`, so a wrapper script can clear an inherited one. This is the half the
/// [`resolve_actor`] cache holds; the git user lives in a cache of its own, because with
/// `--actor-from-git` it has to be fetched even though the variable answered.
fn session_actor(env: Option<&str>) -> Option<String> {
env.map(str::trim)
.filter(|value| !value.is_empty())
.map(str::to_string)
}
/// The actor for one entry: the flag wins, otherwise the session's, otherwise unknown.
/// The actor for one entry, from what named one.
///
/// 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()
///
/// The chain depends on the flag. An explicit `--actor` wins outright either way. With
/// `from_git`, the git user is lifted above the session rather than added beneath it:
/// the flag says attribute this to the human, and a machine with no git user configured
/// has nobody to name, which reads [`UNKNOWN_ACTOR`] rather than quietly attributing
/// back to the agent. Without it, today's chain: the variable, then the git user.
///
/// `git_user` is a closure in both branches so the subprocess it costs is not run when
/// something ahead of it already answered.
fn entry_actor(
flag: Option<&str>,
from_git: bool,
session: Option<&str>,
git_user: impl FnOnce() -> Option<String>,
) -> String {
if let Some(name) = flag.map(str::trim).filter(|value| !value.is_empty()) {
return name.to_string();
}
if from_git {
return git_user().unwrap_or_else(|| UNKNOWN_ACTOR.to_string());
}
if let Some(name) = session.map(str::trim).filter(|value| !value.is_empty()) {
return name.to_string();
}
git_user().unwrap_or_else(|| UNKNOWN_ACTOR.to_string())
}
/// Who to attribute an entry to, from the flag the call carried.
/// Who to attribute an entry to, from the flags 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();
/// Precedence: flag, then — unless `from_git` lifted it — `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>, from_git: bool) -> String {
// Each half is decided once, the way should_use_colors is: neither input can change
// mid-run, and the git user costs a subprocess. They are two caches rather than one,
// because baking the git user into the session's answer would leave `--actor-from-git`
// reading whatever the run's *first* call produced — with the variable set, that call
// never fetched git at all.
static VARIABLE: OnceLock<Option<String>> = OnceLock::new();
static GIT_USER: OnceLock<Option<String>> = OnceLock::new();
let session = SESSION.get_or_init(|| {
let session = VARIABLE.get_or_init(|| {
let env = std::env::var(ACTOR_ENV).ok();
session_actor(env.as_deref(), get_git_user)
session_actor(env.as_deref())
});
entry_actor(flag, session.as_deref())
entry_actor(flag, from_git, session.as_deref(), || {
GIT_USER.get_or_init(get_git_user).clone()
})
}
/// One file a search matched, and where it was found.
pub struct Found {
@@ -712,10 +851,6 @@ pub struct Resolved {
pub campaign: Vec<Cell>,
}
pub fn content_trim_colored(content: &str, resolved: &Resolved) -> String {
content_trim(content, should_use_colors(), resolved)
}
/// A section heading, its rule, and the blank line the body opens under.
///
/// The rule is measured on the name as displayed, in characters. It used to span the
@@ -3288,8 +3423,8 @@ fn show_priority(priority: Priority, colored: bool) -> String {
paint(glyph, colour, colored)
}
pub fn display_ticket_items(items: &[TicketItem]) {
let colored = should_use_colors();
pub fn display_ticket_items(sink: &mut Sink, items: &[TicketItem]) -> Result<()> {
let colored = sink.use_color;
for item in items {
let id = paint(&item.id, Color::Red, colored);
@@ -3298,15 +3433,19 @@ pub fn display_ticket_items(items: &[TicketItem]) {
let priority = show_priority(item.priority, colored);
if item.created.is_empty() {
println!(" {} ({}) {} | Owner: {} | Due: {}", priority, id, item.title, owner, due);
sink.writeln(&format!(
" {} ({}) {} | Owner: {} | Due: {}",
priority, id, item.title, owner, due
))?;
} else {
let created = paint(&item.created, Color::Cyan, colored);
println!(
sink.writeln(&format!(
" {} {} ({}) {} | Owner: {} | Due: {}",
priority, created, id, item.title, owner, due
);
))?;
}
}
Ok(())
}
pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketItem>> {
@@ -3678,48 +3817,99 @@ mod tests {
/// 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");
let session = session_actor(Some("claude"));
let git_user = || Some("Ansho Rei".to_string());
assert_eq!(entry_actor(None, false, session.as_deref(), git_user), "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");
let session = session_actor(Some("claude"));
assert_eq!(
entry_actor(Some("opencode"), false, session.as_deref(), || None),
"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");
let git_user = || Some("Ansho Rei".to_string());
assert_eq!(
entry_actor(None, false, session_actor(None).as_deref(), git_user),
"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.
/// can clear an inherited one and get the git user back. Whitespace is the same
/// case: a shell that quotes a missing value writes one.
#[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");
let git_user = || Some("Ansho Rei".to_string());
for raw in ["", " "] {
let session = session_actor(Some(raw));
assert_eq!(entry_actor(None, false, session.as_deref(), git_user), "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);
let session = session_actor(None);
assert_eq!(entry_actor(None, false, session.as_deref(), || None), UNKNOWN_ACTOR);
// An empty flag falls through rather than writing a blank author
assert_eq!(entry_actor(Some(""), None), UNKNOWN_ACTOR);
assert_eq!(entry_actor(Some(""), false, None, || 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)");
let session = session_actor(Some("claude-code, session 3 (opus)"));
assert_eq!(
entry_actor(None, false, session.as_deref(), || None),
"claude-code, session 3 (opus)"
);
}
/// The flag is the caller acting for the person whose checkout this is: the git user
/// is lifted above the variable rather than added beneath it.
#[test]
fn from_git_lifts_the_git_user_over_the_variable() {
let session = session_actor(Some("claude"));
let git_user = || Some("Ansho Rei".to_string());
assert_eq!(entry_actor(None, true, session.as_deref(), git_user), "Ansho Rei");
}
/// An explicit `--actor` still wins outright beside the lift: it names somebody
/// specific, which is the stronger statement of the two.
#[test]
fn the_flag_wins_over_from_git_too() {
let session = session_actor(Some("claude"));
let git_user = || Some("Ansho Rei".to_string());
assert_eq!(
entry_actor(Some("opencode"), true, session.as_deref(), git_user),
"opencode"
);
}
/// The lift is not a fallback: asked to name the human and finding none configured,
/// the entry reads unknown instead of quietly attributing back to the agent.
#[test]
fn from_git_with_no_git_user_is_unknown_not_the_variable() {
let session = session_actor(Some("claude"));
assert_eq!(entry_actor(None, true, session.as_deref(), || None), UNKNOWN_ACTOR);
}
/// An empty variable still counts as unset with the lift on, which here means the
/// git user answers as usual.
#[test]
fn from_git_leaves_the_empty_variable_unset() {
let git_user = || Some("Ansho Rei".to_string());
assert_eq!(
entry_actor(None, true, session_actor(Some("")).as_deref(), git_user),
"Ansho Rei"
);
}
#[test]
@@ -4637,7 +4827,7 @@ mod tests {
#[test]
fn a_section_rule_matches_the_width_of_its_name() {
let rendered = content_trim_colored("# T\n\n## Description\nbody\n", &Resolved::default());
let rendered = content_trim("# T\n\n## Description\nbody\n", false, &Resolved::default());
// Eleven characters, not fourteen: the rule used to span "## Description"
assert!(rendered.starts_with("Description\n───────────\n"), "{rendered:?}");
@@ -4645,7 +4835,7 @@ mod tests {
#[test]
fn a_non_ascii_section_name_is_not_over_drawn() {
let rendered = content_trim_colored("# T\n\n## Résumé\nbody\n", &Resolved::default());
let rendered = content_trim("# T\n\n## Résumé\nbody\n", false, &Resolved::default());
assert!(rendered.starts_with("Résumé\n──────\n"), "{rendered:?}");
}
@@ -4653,7 +4843,7 @@ mod tests {
#[test]
fn the_body_leaves_the_title_to_cmd_show() {
let rendered =
content_trim_colored("# Only Once\n\n## Description\nbody\n", &Resolved::default());
content_trim("# Only Once\n\n## Description\nbody\n", false, &Resolved::default());
assert!(!rendered.contains("Only Once"), "{rendered:?}");
// And no gap where it was
@@ -4663,7 +4853,7 @@ mod tests {
#[test]
fn the_metadata_section_renders_as_a_table_inside_the_body() {
let content = "# T\n\n## Metadata\n\n- **ID**: abc\n- **Owner**: alice\n";
let rendered = content_trim_colored(content, &Resolved::default());
let rendered = content_trim(content, false, &Resolved::default());
assert_eq!(rendered, "Metadata\n────────\n\nID abc\nOwner alice\n");
}
@@ -4776,7 +4966,7 @@ Plain line with **bold** and a [link](http://x.test/a).
#[test]
fn a_section_after_metadata_still_renders() {
let content = "# T\n\n## Metadata\n\n- **ID**: abc\n\n## Notes\n\nafter\n";
let rendered = content_trim_colored(content, &Resolved::default());
let rendered = content_trim(content, false, &Resolved::default());
assert!(rendered.contains("ID abc"), "{rendered:?}");
assert!(rendered.contains("Notes\n─────\n"), "{rendered:?}");
+14
View File
@@ -574,6 +574,12 @@ fn chmod(path: &Path, mode: u32) {
/// itself, and it is named with the ticket and the path rather than raised as a bare io
/// error. The branch this replaces could not fire at all: the filename carries a fresh
/// uuid, and its message claimed the title was taken.
///
/// The add stages through `write_then_replace` like every other write, so the temp
/// lives under `.worklane/`, outside the directory the chmod keeps closed, and the
/// rename is the step that fails here. Both halves have to be gone afterwards: no half
/// ticket in backlog, and no `.wl-*.tmp` beside it, which is what `stray_files` checks
/// for a move.
#[test]
fn add_names_the_ticket_and_the_path_when_the_write_fails() {
let temp = TempDir::new().unwrap();
@@ -596,6 +602,14 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
chmod(&backlog, 0o755);
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
let strays: Vec<String> = fs::read_dir(&worklane)
.unwrap()
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.filter(|name| name.starts_with(".wl-"))
.collect();
assert_eq!(strays, Vec::<String>::new(), "the staging file was left behind");
}
/// The board above the project is real and empty, and stays empty: a dangling
+46
View File
@@ -262,6 +262,52 @@ fn the_actor_flag_overrides_the_variable() {
assert!(only_comment(&worklane, &uuid).contains("**Author**: opencode"));
}
/// The flag for acting on the person's behalf: their name is what the machine already
/// knows, so the entry does not have to wait for the agent to know it too.
#[test]
fn the_actor_from_git_flag_names_the_git_user_over_the_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "From Git Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.env("GIT_CONFIG_GLOBAL", git_config_naming(&temp, "Configured User"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written for the person"])
.arg("--actor-from-git")
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: Configured User"));
}
/// The lift is not a fallback: with no git user configured there is nobody to name, and
/// the entry reads unknown rather than quietly attributing back to the agent.
#[test]
fn from_git_with_no_git_user_is_unknown_even_with_the_variable() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let uuid = create_ticket(&worklane, "backlog", "No Git User Test");
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.env("GIT_CONFIG_GLOBAL", temp.path().join("no-such-gitconfig"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.arg("comment")
.args([&uuid, "Written with nobody to name"])
.arg("--actor-from-git")
.assert()
.success();
assert!(only_comment(&worklane, &uuid).contains("**Author**: unknown"));
}
/// 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]
+120
View File
@@ -72,6 +72,29 @@ fn run(temp: &TempDir, args: &[&str]) -> Output {
.clone()
}
/// Run as an agent acting for the person: the variable still names the agent, the git
/// config names the human, and the flag is what tells the two apart.
fn run_for_the_human(temp: &TempDir, args: &[&str]) -> Output {
Command::cargo_bin(BIN_NAME)
.unwrap()
.current_dir(temp.path())
.env("WORKLANE_ACTOR", "claude")
.env("GIT_CONFIG_GLOBAL", git_config_naming(temp, "Ansho Rei"))
.env("GIT_CONFIG_NOSYSTEM", "1")
.args(args)
.assert()
.get_output()
.clone()
}
/// 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
}
/// 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);
@@ -562,3 +585,100 @@ fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
}
}
/// The lift is spelled the same on every command that writes an entry, and it raises
/// the git user over the variable on each of them.
#[test]
fn actor_from_git_names_the_git_user_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_for_the_human(&temp, &["comment", UUID, "By hand.", "--actor-from-git"]);
run_for_the_human(&temp, &["mv", UUID, "--status", "committed", "--actor-from-git"]);
run_for_the_human(&temp, &["chown", "bob", UUID, "--actor-from-git"]);
run_for_the_human(&temp, &["set", UUID, "--tags", "beta", "--actor-from-git"]);
run_for_the_human(&temp, &["assign", "v1", UUID, "--actor-from-git"]);
let found = entries(&worklane);
assert_eq!(found.len(), 5, "{found:?}");
for (name, content) in found {
assert!(content.contains("**Author**: Ansho Rei"), "{name}: {content:?}");
}
}
/// Both flags answer the same question — who is the entry attributed to — so a call
/// carrying both is a usage error at parse time rather than a last-wins answer. Refused
/// before any ticket is resolved, so nothing reaches the log.
#[test]
fn actor_and_actor_from_git_are_refused_together() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let calls: [&[&str]; 5] = [
&[
"comment",
UUID,
"Body.",
"--actor",
"opencode",
"--actor-from-git",
],
&[
"mv",
UUID,
"--status",
"committed",
"--actor",
"opencode",
"--actor-from-git",
],
&[
"chown",
"bob",
UUID,
"--actor",
"opencode",
"--actor-from-git",
],
&[
"set",
UUID,
"--tags",
"beta",
"--actor",
"opencode",
"--actor-from-git",
],
&[
"assign",
"v1",
UUID,
"--actor",
"opencode",
"--actor-from-git",
],
];
for call in calls {
let output = run(&temp, call);
assert_eq!(output.status.code(), Some(2), "{call:?} was not a usage error");
}
assert!(
!worklane.join("history").join(UUID).exists(),
"an entry was written despite the usage error"
);
}