Compare commits

...
8 Commits
Author SHA1 Message Date
Ansho Rei f877e6dbf2 (c6a61b4) Resolve a board through a pointer file and a shared boards repo, and bump to 0.33.0 2026-09-01 17:41:05 +02:00
Ansho Rei 3892afe819 (2e05015) Show the campaign standing on its picker row, and bump to 0.32.21 2026-09-01 13:42:51 +02:00
Ansho ReiandClaude Opus 5 c81838efc6 Sort the backlog by due date, then priority
The backlog was the one column priority governed alone, which sat a p1
nobody had promised above a p3 due tomorrow. It has no entry stamp, so it
now takes the due date as the date `by_status_order` keys on: soonest
first, undated below every dated one, and priority then title as the
tiebreak, which is still the whole order among the undated ones.

`TicketItem::due_key` is where a due becomes an orderable date. Only a
plain `YYYY-MM-DD` counts, which is all `--due` has accepted since
daa0e79, with `due_date` cutting a legacy datetime back to its date.
Free text answers `None` and sinks with the unset ones rather than
sorting on its spelling: a due nobody can place on a calendar is
unknown, the same reading a missing stamp already gets.

The comparator stays the single function keyed on `Status`, so `ls`,
`ls --ids`, the board's columns and `campaign::members` move together.
The All tab keeps `by_priority_then_title`: that merge spans statuses,
so no single date governs it.

`ls_listed_tickets_sorted_alphabetically` gave its three tickets three
different due dates while asserting title order. They share one now, so
the case still tests the tiebreak it names rather than the new order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-01 01:10:41 +02:00
Ansho ReiandClaude Opus 5 cd7c99fe39 (d5a8a3f) Add make check, one command for fmt, clippy and the suite, and bump to 0.32.20
AGENTS.md pins `cargo fmt --check` and `cargo clippy --all-targets` as
clean, and 83d31cd is what happens when only memory enforces that: fmt
drifted to about 160 places across every file with the tool installed and
configured by default the whole time.

The decision the ticket wanted, taken: mechanise it, as one command. Not
CI, which a single-author tool with no pipeline anywhere does not want,
and not a hook, which is a per-clone opt-in the way `blame.ignoreRevsFile`
is and so cannot be relied on either. What was missing was never a
mechanism, it was one name to type: "remember to run fmt, clippy and the
tests" becomes `make check`.

Cheapest first, so a formatting slip is reported in a second rather than
after the suite. `-D warnings` is what turns clippy's opinion into an exit
code, since a warning printed into a wall of cargo output is unread rather
than clean. Verified each gate fails on its own: a misformatted function
and a `&Vec<u8>` parameter each exit 2 before the tests run.

Completions are inside `cargo test` rather than a target of their own.
d93eca6 put the check that loads the generated script into a real fish
there, so "check tests, check completions" is already one command, and a
second target would be a second thing to remember, which is the problem
this is solving.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 23:56:44 +02:00
Ansho ReiandClaude Opus 5 b63b60eefc (4dea61c) Load the completion script into fish and ask it what it offers, and bump to 0.32.19
Every check over the completions read the script as text. A `contains`
cannot tell a rule that fires from one whose condition stopped matching,
and that is how a completion actually breaks: the clap definition moves,
a list or a `__worklane_command_is` scope stops naming anything, and the
rule sits in the file offering nothing while every assertion passes.

So the generated script is sourced into a throwaway fish standing in a
real board, with this build's directory on the front of PATH, and
`complete -C` is compared against the ticket and the tag that board was
given. Four deliberate breakages were used to size it: renaming the `ls`
status scope, dropping `append` from `TAG_FLAGS`, renaming a flag in
`TICKET_FLAGS` and dropping `show` from `TICKET_COMMANDS`. All four now
fail, each naming the list at fault.

**Assert the values, not the flag names.** clap emits every option's name
on its own, so `--tags` and `--blocked-by` are offered with the whole
dynamic half deleted; the first draft asserted those names and caught
only one of the four. What the hand-written rules add is the candidates
after the flag, and that is what a board under the shell makes checkable.

Two traps, both paid for once. `complete -C` autoloads
`~/.config/fish/completions/worklane.fish`, so the first draft passed
against a deliberately broken scope because the copy installed in August
still had the working rule: `set fish_complete_path` with no value is
what makes the sourced script the only source, and without that line the
test cannot fail. And the script is written beside the board rather than
in it, since a rule that fires nothing falls back to listing the
directory and the script would read as an answer.

`fish --no-execute` comes with it as the floor: it catches a script that
does not parse. Narrower than it sounds, and measured rather than
assumed, so the limit is written on the test. An apostrophe in a `-d`
description partway down re-balances against the next quote and parses,
corrupting every rule in between; the same apostrophe in the last rule
reaches the end unbalanced and is caught.

`every_listed_command_is_a_real_subcommand` widens to every list that
names a command, `CAMPAIGN_COMMANDS`, `TAG_FLAGS` and the two nested
lists, so a stale entry fails by name instead of through a rule count.
The counts themselves stay hardcoded and now say why: the walkers go
clap → list and never see an extra entry, so the count is what catches
one, and deriving it from the lists it checks would grow with the bogus
entry and pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 23:54:48 +02:00
Ansho ReiandClaude Opus 5 7470255a22 (a1a5d69) Add tags to a ticket with append --tags, keeping the ones it carries, and bump to 0.32.18
`set --tags` writes the whole field, so adding one tag to a ticket that
already carries some meant reading it first and retyping every one of
them. 30a2b34 wrote that down in the skill as the way to do it; this is
the flag that makes it unnecessary.

The merge is idempotent and ordered. A tag the ticket already carries is
reported as no change rather than added twice, which is the point of the
flag: the caller does not have to know what is there. A new one goes on
the end in the order it was given rather than sorting the field under
whoever last touched it. Values are split on commas the way the stored
field is, so `--tags "bug, tui"` names two tags and matches the two a
ticket carrying them already holds; without that the pair would land as
a single tag nothing can filter by and would not match itself on the
next call. `split_tags` is that rule, lifted out of `parse_tags` so the
argument and the field are separated by the same code.

It writes the same `Kind::Tags` entry `set --tags` writes, so `--actor`
and `--actor-from-git` come with it. Tags are logged wherever they move,
and the one command that adds to them without replacing them would
otherwise be the one tag change the log missed. The before and after are
read off the field rather than off the flag, so an append of `beta` onto
`alpha` reads as the pair and not as what the call asked for.

`non_empty` rather than the `clearable` that `set --tags` takes: that
message names `--clear`, and `append` has none, so it would send the
caller looking here for a flag that is `set`'s. A value that is only
separators reaches the handler and is refused there, in the words
`appended_items` refuses an all-blank section with. Emptying the field
stays `set --clear tags`.

`TAG_FLAGS` becomes pairs of command and flag, because `ls --tag` and
`append --tags` are spelled differently and one rule naming both options
would tell fish that each command accepts the other's. `add --tags` and
`set --tags` deliberately get no value rule and are recorded in the
test's `TAG_LIST_FLAGS` instead: they take the whole list, so the token
at the cursor is `bug,tui` and fish replaces a token entire, throwing
away what is already typed. The honesty test now walks `tag` and `tags`
both, so the next tag argument has to say which of the two it is.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-31 23:37:33 +02:00
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
21 changed files with 3597 additions and 259 deletions
+97 -12
View File
@@ -1,13 +1,14 @@
# 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
- `src/util.rs` - the ticket format, resolution, rendering and the palette
- `src/campaign.rs` - the campaign file format, its resolution, its index and its members
- `src/history.rs` - the history log: the path, the kinds, the reader, the writer, the card's counter and the block `show` and the board both render
- `src/board.rs` - the shared-board layout: the machine config, the boards directory, the `.worklane.toml` pointer and the `init` decision table that decides which layout a project is on
- `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
@@ -29,7 +30,7 @@
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Discarded On`, `Campaign`, `Status`. The last five are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
- The four stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
- **`Discarded` is last in `Status::ALL`, and that placement is what makes the stamp rule fall out right.** Nothing sits after it, so a discard clears nothing: a ticket abandoned from reviewing keeps `Committed On` and `Submitted On`, and the file still says how far it got before it was dropped. It also makes every move out of discarded a backward move, so un-discarding needs `-f` without a rule of its own. `Discarded On` is its stamp, and `Completed On` stays untouched, because a discarded ticket was never done
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
- **Each status column is ordered by its own date, through `by_status_order`.** Past the backlog that date is the entry stamp, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done and discarded by their stamp descending. The backlog has no stamp of its own, so it sorts by `Due` ascending, through `TicketItem::due_key`. Said once: the head of every column is what the reader acts on next, and in the backlog that is the nearest deadline rather than the loudest priority — priority alone sat a p1 nobody had promised above a p3 due tomorrow. A ticket carrying no date sinks below every dated one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal dates and both-undated fall through to `by_priority_then_title`, which is still the whole order among undated backlog tickets. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The dates are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` and `%Y-%m-%d` are both lexicographic in chronological order, so nothing parses a date at sort time. `due_key` answers `None` for a `Due` that is not a plain `YYYY-MM-DD` after `due_date` has cut a legacy datetime back — free text is unknown, not a date, and sorting on its spelling would rank it against real deadlines
- Format: `**Field Name**: value`
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
@@ -52,8 +53,71 @@ rule and the argument traps are written down. Read it before working a ticket in
repo. Do not restate any of it in this file: a second copy is a copy that goes stale,
and this file is for what someone changing worklane's own code needs.
## Shared Boards
- **A project's board is on one of two layouts, and `src/board.rs` is the whole of the
second one.** The local layout is the `.worklane` directory a project has always had.
The shared layout answers `.worklane` being gitignored and not a git repo so a clone
elsewhere has no board: the project commits a `.worklane.toml` naming its board by
uuid, one boards repo is cloned once per machine, and `.worklane` in the project
becomes a *symlink* into it. The symlink is the point: with no `.worklane` directory
`cat .worklane/backlog/*.md` and `ls .worklane/reviewing` would stop working, and that
is the belief the whole file format exists to serve. Because the link is transparent,
`find_worklane_dir` gains no resolution code at all (c6a61b4 AC 14).
- **The machine config lives at `$XDG_CONFIG_HOME/worklane/config.toml`** (default
`~/.config`, empty counts as unset). It carries a `[boards]` section holding the *url*
of the boards repo and an optional `dir` overriding where the boards directory sits —
the config is *this machine's* answer, and the pointer carries no server address, so a
client repo never holds an internal hostname. The boards directory itself defaults to
`$XDG_DATA_HOME/worklane/boards` (`~/.local/share` without it).
- **The pointer is `.worklane.toml`, committed at the project root:**
`[worklane] board = "<uuid>"`, and nothing else. Read and written by `read_pointer` /
`write_pointer`. `write_pointer` leaves a pointer that already names the same board
alone — it is a committed file and rewriting it writes nothing new, which is what keeps
"init symlinks it and creates nothing" true for a fresh clone.
- **A board directory is `<uuid>_<slug>`, named after the ticket files.** The slug is
`util::slug` of the project's directory name, and resolution (`resolve_board`) is a
uuid prefix match, the bargain the ticket filenames already make: the directory stays
readable to `ls`, identity is stable, and renaming a board breaks no committed pointer.
- **The decision table is `decide_init`, one match.** The reason it is a table rather
than a fallback is that no branch may fall through into creating a board, so each row
returns its own outcome. The rows:
- no pointer, no `[boards]` config → local `.worklane`, exactly as `init` always made
it (AC 12);
- no pointer, config present → create the board, write the pointer, symlink `.worklane`
to it (AC 4);
- pointer present, board found → symlink it and create nothing (AC 5);
- pointer present, board absent → refuse. A committed pointer is proof the board exists
somewhere, so a missing board is an unsynced machine, and creating a second board
there produces two boards with one name and a manual merge — the worst outcome in the
design. The refusal says so and names `init --create` as the only way to make one
(AC 6/7). The fetch-and-look-again half of the ticket is deferred: nothing pulls the
boards repo yet, and the refusal names it rather than doing it. **`--create` is the
`create` field on `Command::Init`**, the escape hatch under that row;
- the boards directory itself missing → a distinct refusal saying the boards repo is
not cloned here (AC 8);
- the correct symlink already in place → no change, nothing written (AC 9);
- a symlink to a *different* board → refuse rather than repoint it: changing what a
project is on without asking is how two machines come to disagree about the work
(AC 10);
- a symlink that dangles → refuse rather than replace it without asking;
- a real `.worklane` directory under a pointer → refuse and name the adopt path
(aa80db4), never walk over it (AC 11).
- **The three symlink states are told apart by `classify_worklane`:** `Absent`,
`RealDir`, `Symlink`, `Dangling` and `NotADirectory`. The `Symlink` comparison is
canonicalized, the `Dangling` one is lexical (a dangling link cannot be canonicalized)
and checks for the relative spelling this tool writes or the absolute board path.
- **The symlink target is relative** to the link's own parent, so it uses no home
directory path and the link is portable in that limited sense; an absolute target
appearing anywhere is how a home directory leaks into a write. Because a relative
target depends on how deep a repo sits, `init` still runs once per project per machine,
which is the price of transparent access.
- **Everything under `.worklane` is layout-agnostic.** `create_board_contents` makes the
same status directories, `campaigns/` and `tags.md` for a local and a shared board,
and every reader below `find_worklane_dir` works through the link unchanged.
## Testing
- Run: `cargo test`
- **Run `make check` before committing**: `cargo fmt --check`, then `cargo clippy --all-targets -- -D warnings`, then `cargo test`, cheapest first. That is the whole of the enforcement, and it is deliberate rather than a stopgap: this repo has no CI and does not want any, and a git hook is a per-clone opt-in the way `blame.ignoreRevsFile` is, so neither can be relied on. What was missing was one name to type, so the two rules below are a command and not a memory. `-D warnings` is what makes clippy's opinion an exit code; a warning printed into a wall of cargo output is unread, not clean. The completion checks are inside `cargo test` rather than a target of their own, since a second thing to remember is the problem this solves
- Run one suite: `cargo test`
- Tests use `assert_cmd` and `assert_fs` for CLI testing
- `setup_worklane()` creates temp `.worklane/` with the four flow status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it. **The fixtures deliberately do not create `discarded/`**, so every discard test runs against a board that predates the status and `mv_creates_the_discarded_directory_on_a_board_that_predates_it` is not the only thing exercising the on-demand creation
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
@@ -62,8 +126,8 @@ and this file is for what someone changing worklane's own code needs.
- **`WORKLANE_KEEP_FIXTURES=1 cargo test` keeps the fixtures and prints each path.** Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and `Fixture::swept()` turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment
- **Verify a claim about leaked fixtures against a clean temp dir, not against `/tmp`.** `TMPDIR=/tmp/scratch cargo test` then count what is left in it: `/tmp` still holds the historical leak, so counting there measures the past rather than the change
- In `tui.rs`, `write_member_card` is `write_tagged_card` plus a Campaign field and `write_campaign` puts a campaign on disk, creating the campaigns directory as it goes — `board_dir()` deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. `picker_rows` cuts the picker's list out of the frame by its own geometry, for the reason `overlay_title_row` exists: a card carries the same campaign label, so a search over every row finds the board rather than the list
- **`cargo clippy --all-targets` is clean. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
- **`cargo fmt --check` is clean too, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
- **`cargo clippy --all-targets` is clean, and `make check` is what says so. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
- **`cargo fmt --check` is clean too, `make check` runs it first, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
| setting | value | why |
|---|---|---|
@@ -96,7 +160,7 @@ and this file is for what someone changing worklane's own code needs.
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
- **`campaign add --codename` is validated at parse time by `codename`**, which is `non_empty` plus one word. The board draws it as a label with a mark and no quoting, so `~beaver release` on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason `ls --tag` refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser. **`append --tags` is the one place the field has an empty form and the argument still takes `non_empty`**: `append` has no `--clear` of its own, so naming one would send the caller looking on this command for a flag that is `set`'s
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
- A bare `--` is a value when it follows an option (`--title -- ` stores `--`) and clap's end-of-options marker when it sits in a positional. So a `comment` body of exactly `--` needs its own separator, `comment <ticket> -- --`. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop
@@ -111,8 +175,12 @@ and this file is for what someone changing worklane's own code needs.
- **What clap does and does not emit.** It emits the possible values of an *option*, which is why `mv --status <TAB>` needs nothing here, and nothing for a *positional*, which is why the `ls` status and the `completions` shell are listed in the fish half. Both lists are read off the enums with `possible_values`, never written out, so a fifth status appears in the script on its own
- **Position is counted, not inferred.** The four `__worklane_*` predicates all read `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition. `first_arg_of` and `second_arg_of` count a top-level command's arguments, `nested_arg_of` matches a parent and a child so `campaign show <TAB>` can be told from `chown alice <TAB>`, which sit at the same token count, and `command_is` asks only which command this is, at any position in it
- **Every rule carrying `-l` needs a `__worklane_command_is`, and `every_rule_naming_an_option_is_scoped_to_a_command` is what enforces it.** A bare `complete -c worklane -l tag` does not just complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --<TAB>` offered six options that only `relate` and `ls` have. Fixed in 55ee6e3. `__fish_seen_subcommand_from ls` is not the scope to use, for the nesting reason above
- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
- **The strongest completion check loads the script into fish and asks it for candidates.** `fish_offers_the_commands_the_statuses_and_the_values` in `tests/cmd_completions.rs` sources the generated script into a throwaway shell standing in a real board, with this build's directory on the front of PATH, and compares `complete -C` against the ticket and the tag it put there. Every other test in the file reads the script as text, which cannot tell a rule that fires from one whose condition stopped matching, and that is how a completion actually breaks. **Assert the values, not the flag names**: clap emits every option's name on its own, so `--tags` and `--blocked-by` are offered with every hand-written rule deleted; what the dynamic half adds is what comes *after* the flag. Two traps, both paid for once: the shell must have `fish_complete_path` emptied, or `complete -C` autoloads `~/.config/fish/completions/worklane.fish` and answers from whatever version wrote that, which is a guard that cannot fail; and the script is written beside the board rather than in it, since a rule that fires nothing falls back to listing the directory
- **`fish --no-execute` is the floor under that, not an oracle.** It catches a script that does not parse, quotes still open at the end of the file or an unclosed block. Measured, not assumed: an apostrophe interpolated into a `-d` description partway down re-balances against the next quote and parses, corrupting every rule in between while the check passes; the same apostrophe in the last rule reaches the end unbalanced and is caught. Only fish gets this, because only fish gets a hand-written half
- **The rule counts in the completion tests are hardcoded on purpose.** The walkers go clap → list and never see an entry naming something that does not exist, so a bogus pair in `TAG_FLAGS` is caught by `every_tag_rule_takes_the_annotation_as_its_description` counting one rule too many. Deriving that number from the lists it checks would grow with the bogus entry and pass. The `seen` totals in the walkers are hardcoded for the mirror reason, and both carry the note
- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise, the last against the test-local `TAG_LIST_FLAGS` and `TAG_NEW_COMMANDS` for the tag arguments that deliberately get no rule. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
- **A campaign is named in three shapes and a tag in one**, which is why the lists are not one list: a campaign is `assign`'s first positional, the first argument of `campaign show` and `campaign set`, and `ls --campaign`'s value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command
- **`TAG_FLAGS` holds pairs where the others hold names**, because the two options that take one tag are spelled differently: `ls --tag` filters on one and `append --tags` adds them, so a single rule naming both would tell fish that each command accepts the other's flag. One rule per pair, generated in `fish_dynamic`. `add --tags` and `set --tags` are in the test's `TAG_LIST_FLAGS` instead and get no rule: they take the *whole* list, so the token at the cursor is `bug,tui` and fish replaces a token entire, which would throw away what is already typed. The test walks both `tag` and `tags`, so the next one has to say which of the two it is
- **`ls --ids` is the machine-readable listing**, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused
- **`campaign ls --ids` is the same flag and the same two fields for the other object**, and it deliberately skips the member counting the decorated listing does: `members()` reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates
- **`worklane tags` is the third, and it is a command rather than a mode on `ls`.** Two reasons: `ls --tag <tag>` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so `bug` and `Bug` list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. `assets/PLAN.md` used to tell the agent to count tags with a `show` per ticket, and now points here
@@ -353,15 +421,32 @@ and this file is for what someone changing worklane's own code needs.
### 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 no `Size`, because nothing it does measures the board — the keypress that will is 53ffb94, which redraws on what the command wrote. 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
- **`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 resolves the line and does not run it**, so the notice says `parsed, not run yet` rather than reading like a move that happened, and the prompt's own key is drawn as `↵ check`. Both are replaced by 53ffb94, which is the ticket that runs it; naming the key `run` here would be the fault 1b78a24 was, in the other direction
- **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
- `: 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
@@ -429,7 +514,7 @@ and this file is for what someone changing worklane's own code needs.
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `visibility` stays on the board because it is a preference about the flow rather than about a project
- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so `Board::new` builds the tab list once and `reload` only refills each tab's columns. `reload` clamps **every** tab, and `select_tab` clamps again on arrival, because done may have been hidden while another tab was in view
- The merge tab goes **first** and is where the view opens: it is the reason to monitor several boards at once. It is materialised in `reload`, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in `collect_ticket_items`
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single date governs it
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
@@ -461,7 +546,7 @@ and this file is for what someone changing worklane's own code needs.
- **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. `--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
- **`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. `append --actor` is the same flag for the same reason: `append --tags` moves the same field, so it writes the same `Kind::Tags` entry, and a tag added without replacing the rest would otherwise be the one tag change the log missed
### Shipping the Agent Assets
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
Generated
+63 -1
View File
@@ -896,6 +896,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
dependencies = [
"serde_core",
"serde_derive",
]
[[package]]
@@ -931,6 +932,15 @@ dependencies = [
"zmij",
]
[[package]]
name = "serde_spanned"
version = "0.6.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
dependencies = [
"serde",
]
[[package]]
name = "shlex"
version = "1.3.0"
@@ -1055,6 +1065,47 @@ version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
[[package]]
name = "toml"
version = "0.8.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
dependencies = [
"serde",
"serde_spanned",
"toml_datetime",
"toml_edit",
]
[[package]]
name = "toml_datetime"
version = "0.6.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
dependencies = [
"serde",
]
[[package]]
name = "toml_edit"
version = "0.22.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
dependencies = [
"indexmap",
"serde",
"serde_spanned",
"toml_datetime",
"toml_write",
"winnow",
]
[[package]]
name = "toml_write"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
[[package]]
name = "unicode-ident"
version = "1.0.24"
@@ -1407,6 +1458,15 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "winnow"
version = "0.7.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
dependencies = [
"memchr",
]
[[package]]
name = "wit-bindgen"
version = "0.51.0"
@@ -1503,7 +1563,7 @@ dependencies = [
[[package]]
name = "worklane"
version = "0.32.15"
version = "0.33.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -1514,7 +1574,9 @@ dependencies = [
"crossterm",
"libc",
"ratatui",
"serde",
"tempfile",
"toml",
"uuid",
]
+3 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "worklane"
version = "0.32.15"
version = "0.33.0"
edition = "2024"
[dependencies]
@@ -15,6 +15,8 @@ libc = "0.2"
ratatui = { version = "0.29", features = ["unstable-rendered-line-info"] }
crossterm = "0.28"
clap_complete = "4.6.9"
serde = { version = "1", features = ["derive"] }
toml = "0.8"
[dev-dependencies]
assert_cmd = "2"
+23 -1
View File
@@ -5,15 +5,37 @@
# release cannot end up half-done: no version bump left untagged, no tag without
# a bump.
.PHONY: help patch minor major version release install
.PHONY: help check patch minor major version release install
help:
@echo "make check fmt, clippy and the suite, in that order"
@echo "make patch bump $(CURRENT) -> next patch, amend into HEAD, tag"
@echo "make minor bump $(CURRENT) -> next minor, amend into HEAD, tag"
@echo "make major bump $(CURRENT) -> next major, amend into HEAD, tag"
@echo "make version print the current version"
@echo "make install cargo install --path . && worklane install-skill"
# The one command to run before committing. AGENTS.md pins fmt and clippy as clean and
# 83d31cd is what happens when only memory enforces that: fmt drifted to about 160 places
# across every file with the tool installed and configured the whole time. This is not CI,
# which a single-author tool with no pipeline anywhere does not want, and not a hook, which
# is a per-clone opt-in the way `blame.ignoreRevsFile` is. It is one name to type, so
# "remember to run fmt, clippy and the tests" becomes "run make check".
#
# Cheapest first, so a formatting slip is reported in a second rather than after the suite.
# `--all-targets` on clippy, matching the rule in AGENTS.md, so the tests are linted too.
# `-D warnings` is what makes clippy's opinion an exit code: the rule says clean, and a
# warning printed into a wall of cargo output is not clean, it is unread.
#
# Completions are in the suite rather than a step of their own. `cargo test` sources the
# generated script into a real fish and asks it for candidates, so "check tests, check
# completions" is one command already, and a second target would be a second thing to
# remember. The fish tests skip when fish is not installed, printing that they did.
check:
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
# Read from the [package] table of Cargo.toml, which is the version the binary
# reports through `--version`, so it is the single source of truth. The name is
# what finds this crate's own entry in Cargo.lock.
+43 -3
View File
@@ -6,13 +6,13 @@ Worklane is a local Kanban flow for agentic software development.
| Command | Description |
|---------|-------------|
| `worklane` or `worklane tui [path...]` | Opens the board: one column per status, redrawn when the tree changes. Read only. Opens with done and discarded hidden, their counts in the footer; `d` rotates hide both, show done, show both, and back around. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done, discarded directories |
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done, discarded directories. On a machine with a boards config, or in a project that already carries a `.worklane.toml`, it puts the project on the shared layout instead: the board lives in a boards directory under the machine's data dir and `.worklane` becomes a symlink into it. `--create` makes a new board under a pointer that names a missing one, the only way to do so. See Shared Boards |
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
| `worklane ls [status]` | Lists tickets, each column in its own order: the backlog by due date, soonest first, then priority then title, with an undated ticket below every dated one; committed and reviewing by when the ticket entered them, oldest first; done and discarded newest first. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. `--status discarded` is exempt and reachable from anywhere, for a ticket that will not be done; leaving `discarded` is a backward move and needs `-f`. Discarding is refused while open tickets are blocked by the ticket, `-f` overrides. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`, or to the tags with `--tags`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last. `--tags` keeps the tags the ticket already carries, ignores one it already has, and takes several as a repeated flag or separated by commas, the way the field itself is written; it is the counterpart to `set --tags`, which replaces the whole field. It records a `tags` entry in the ticket's history, and `--actor` names the writer of that entry, this command's only logged field as it is `set`'s. Emptying a field is `set --clear`, which has no counterpart here |
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning, and a derived row that reads exactly like a stored one is drawn once. `relates to` on a ticket whose target already stores it reports no change, since it is the same edge; `blocked by` and `regression of` read differently from the far end, so a mutual pair is two rows. `mv` refuses to move a ticket blocked by one that is not done, unless `-f`. `--clear <kind> <target>` takes an edge off instead, repeatable, the kind spelled either way, `blocked-by` or `blocked by`. The target resolves against the edges the ticket holds first, by id prefix, which is the only way to reach one whose ticket has been deleted, then as an ordinary ticket search. An edge the ticket does not hold reports no change; a target naming nothing at all is an error. Recording and clearing the same edge in one call is refused |
| `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 |
@@ -70,6 +70,35 @@ installed binary to be current**: an older one without `--ids` completes nothing
`tui` is the one command whose argument is a path, so it is the one place fish still offers
directories.
## Shared Boards
A board exists on exactly one machine: `.worklane` is gitignored and not itself a git repo, so cloning
a project elsewhere gives you no board. The shared layout answers that: one boards repo is cloned once
per machine to `~/.local/share/worklane/boards`, holding a directory per board named `uuid_slug` after
the ticket filename convention; the project commits a `.worklane.toml` naming its board by uuid; and
`.worklane` in the project becomes a symlink into it. The symlink is what keeps every other tool
working — with no `.worklane` directory, `cat .worklane/backlog/*.md` stops.
The boards repo url lives in the machine config at `~/.config/worklane/config.toml`, so a client repo
never carries a hostname. The pointer names the board, not the server.
`init` decides where a project is on by the following table, and `--create` is the only way to make a
board under a pointer that names a missing one:
| pointer | boards repo | `.worklane` | outcome |
|---|---|---|---|
| none | irrelevant | none | local `.worklane`, as always |
| none | on this machine (config) | none | create the board, write the pointer, symlink |
| present | board found | none | symlink, and nothing is created |
| present | board absent | none | refuse: an unsynced machine, fetch and look again |
| present | repo not cloned | any | refuse, saying the repo is not cloned here |
| present | board found | link to it | no change, nothing written |
| present | board found | link to another | refuse rather than repoint |
| present | board found | dangling link | refuse rather than replace |
| present | board found | real directory | refuse, and name the adopt path |
Resolution is a uuid prefix match, so renaming a board's slug breaks no committed pointer.
## Exit codes
| Code | Meaning |
|------|---------|
@@ -88,6 +117,17 @@ the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer who
and the writer never learns the reader left, giving 0. Only output past that gets far
enough to be cut off. Either way nothing is printed to stderr.
## Checking
```sh
make check # cargo fmt --check, clippy -D warnings, cargo test
```
One command, cheapest first, and the whole of what enforces the formatting and lint rules:
there is no CI here and no hook. The completion tests inside it source the generated script
into a real fish and ask it what it would offer, so they skip, saying so, on a machine
without fish.
## Releasing
```sh
+27 -8
View File
@@ -169,16 +169,21 @@ worklane set 1b78a24 --clear due # take a value away again
worklane set 1b78a24 --clear tags --clear plan # as many fields as you like
worklane append 1b78a24 --acceptance "One more criterion"
worklane append 1b78a24 --description "What was learned since."
worklane append 1b78a24 --tags tui # add a tag, keeping the ones there
worklane chown alice 1b78a24 # hand the ticket to someone
worklane chown --clear 1b78a24 # hand it back to nobody
```
`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.
field, so **use `append --tags` to add a tag to a ticket that already carries some**: it
keeps what is there, and a tag the ticket already has is reported as no change rather
than added twice, so you do not have to read the ticket first. Several in one call by
repeating the flag or by separating them with commas, `--tags "bug, tui"`, since that is
how the field itself is written. Reach for `set --tags` when the whole list is being
replaced, and `set --clear tags` to empty it: `append` has neither. 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`
@@ -197,6 +202,19 @@ resolve as a ticket. `--clear` replaces both arguments with the ticket alone.
`worklane init` creates `.worklane/` with the five status directories and the campaigns
directory beside them, for a repo that has no board yet.
**A board can be shared across machines.** `.worklane` is gitignored and not itself a git
repo, so a clone elsewhere has no board. The shared layout keeps one boards repo cloned
once per machine, a committed `.worklane.toml` in the project naming its board, and
`.worklane` as a symlink into the boards directory — transparent to every command. Where
to run `init` decides the layout: a project whose machine carries a boards config, or
whose repo already shows a `.worklane.toml`, lands on the shared board, and everything
else gets the ordinary local `.worklane`. A pointer whose board is missing is an unsynced
machine and `init` refuses rather than creating a second board that would have to be
merged by hand; `worklane init --create` is the deliberate exception for a genuinely new
board. You only need the layout in mind when a `.worklane.toml` appears in a repo you
are working in: it says the board is another machine's, and a missing one means pull the
boards repo, not that the board never existed.
## Relating tickets
```
@@ -339,8 +357,8 @@ existing ticket will have been written from a different angle.
`show` ends with a HISTORY block: every comment on the ticket and every change to its
status, owner, tags or campaign, oldest first, each naming who made it. You do not write
these by hand. `mv`, `chown`, `set --tags` and `assign` record themselves, and a call
that changes nothing records nothing. A campaign move is recorded by codename, or by
these by hand. `mv`, `chown`, `set --tags`, `append --tags` and `assign` record
themselves, and a call that changes nothing records nothing. A campaign move is recorded by codename, or by
title for a campaign that has none, not by the uuid the field holds.
```
@@ -380,7 +398,8 @@ you to move a ticket, or to put words on the board as their comment, so name the
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`.
`mv`, `chown`, `set`, `append` and `assign`. On the last two it reaches only the entry
`--tags` writes, since that is the one field either of them logs.
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
+16 -3
View File
@@ -358,7 +358,7 @@ export const set = tool({
export const append = tool({
description:
"Add to a section of an existing worklane ticket without replacing what is there. The description gains a new paragraph; acceptance criteria and plan steps are added to the end of their lists, with steps numbered on from the last. Ticked criteria and handwritten content are left alone. To replace a section outright, use set.",
"Add to an existing worklane ticket without replacing what is there. The description gains a new paragraph; acceptance criteria and plan steps are added to the end of their lists, with steps numbered on from the last; tags are added to the ones the ticket already carries. Ticked criteria and handwritten content are left alone. To replace a section or the whole tag list outright, use set.",
args: {
ticket: tool.schema
.string()
@@ -375,6 +375,14 @@ export const append = tool({
.string()
.describe("Implementation plan steps to add, one per line.")
.optional(),
tags: tool.schema
.string()
.describe("Tags to add, comma separated, keeping the ones the ticket already carries. A tag it already has is reported as no change rather than added twice, so the ticket does not have to be read first.")
.optional(),
actor: tool.schema
.string()
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
.optional(),
},
async execute(args: Record<string, any>, context: ToolContext) {
if (!args.ticket) {
@@ -395,9 +403,14 @@ export const append = tool({
if (args.plan) {
itemLines(args.plan).forEach((line: string) => cmd.push("--plan", line));
}
if (args.tags) cmd.push("--tags", args.tags);
// Last, and not counted as a field: the length check below is what refuses a call
// that names nothing to add, and an actor alone adds nothing. Same shape as set.
const fields = cmd.length;
if (args.actor) cmd.push("--actor", args.actor);
if (cmd.length === 2) {
return "Error appending: give at least one section to add to";
if (fields === 2) {
return "Error appending: give at least one field to add to";
}
try {
+615
View File
@@ -0,0 +1,615 @@
//! Shared boards: the `.worklane.toml` pointer, the machine config, the boards
//! directory and the symlink that makes a shared board transparent.
//!
//! A board exists on exactly one machine: `.worklane` is gitignored and not itself a
//! git repo, so a project cloned elsewhere has no board. The shared layout answers that
//! with a boards repo cloned once per machine, holding one directory per board named
//! `<uuid>_<slug>` after the ticket filename convention. The project carries a
//! committed `.worklane.toml` naming its board by uuid, and `.worklane` in the project
//! becomes a *symlink* into the boards directory. A symlink rather than resolving the
//! pointer inside the CLI, because with no `.worklane` directory `cat
//! .worklane/backlog/*.md` and `ls .worklane/reviewing` would stop working, and that is
//! the belief the whole file format exists to serve. The symlink keeps every other tool
//! working and `find_worklane_dir` needs no resolution code, because it already follows
//! a link.
//!
//! The pointer names the board, not the server: the boards repo url lives in the
//! machine config, so a client repo never carries an internal hostname for anyone with
//! access to it to read.
use anyhow::{Result, anyhow};
use std::fs;
use std::path::{Path, PathBuf};
use crate::util::slug;
/// The one file that decides whether this project's board is shared or local.
const POINTER_FILE: &str = ".worklane.toml";
/// Where the machine-level config lives, under `$XDG_CONFIG_HOME`, or `~/.config`
/// without it, the same resolution `install::tools_root` follows.
fn config_path() -> PathBuf {
xdg_config().join("worklane/config.toml")
}
/// The boards directory, under `$XDG_DATA_HOME`, or `~/.local/share` without it.
///
/// The ticket's spelling is `~/.local/share/worklane/boards`.
fn default_boards_dir() -> PathBuf {
xdg_data().join("worklane/boards")
}
/// `$XDG_CONFIG_HOME` or `~/.config`, the convention `install::tools_root` already
/// follows. An empty value counts as unset, like `NO_COLOR` in `colors_wanted`.
fn xdg_config() -> PathBuf {
match std::env::var_os("XDG_CONFIG_HOME") {
Some(value) if !value.is_empty() => PathBuf::from(value),
_ => home().join(".config"),
}
}
/// `$XDG_DATA_HOME` or `~/.local/share`.
fn xdg_data() -> PathBuf {
match std::env::var_os("XDG_DATA_HOME") {
Some(value) if !value.is_empty() => PathBuf::from(value),
_ => home().join(".local/share"),
}
}
fn home() -> PathBuf {
std::env::var_os("HOME").map(PathBuf::from).unwrap_or_default()
}
/// The machine's boards configuration, `None` when neither the file nor a `[boards]`
/// section exists.
///
/// Holding the boards repo url and the board directory path. The directory defaults
/// under `$XDG_DATA_HOME` but is overridable here.
pub fn read_config() -> Result<Option<MachineConfig>> {
let path = config_path();
let text = match fs::read_to_string(&path) {
Ok(text) => text,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(anyhow!("Could not read the machine config {}: {error}", path.display()));
}
};
let parsed: ConfigFile = toml::from_str(&text).map_err(|error| {
anyhow!("Could not parse the machine config {}: {error}", path.display())
})?;
Ok(parsed.boards.option())
}
/// The effective boards directory, config override or default.
pub fn boards_dir() -> Result<PathBuf> {
Ok(read_config()?
.and_then(|config| config.boards_dir)
.unwrap_or_else(default_boards_dir))
}
#[derive(Default)]
pub struct MachineConfig {
/// The boards repo url. Read and held so the config carries it (the pointer names
/// the board, the machine names the server), and not yet read anywhere further:
/// the fetch that would use it is deferred.
#[allow(dead_code)]
pub url: Option<String>,
pub boards_dir: Option<PathBuf>,
}
#[derive(serde::Deserialize, Default)]
struct ConfigFile {
#[serde(default)]
boards: BoardsSection,
}
#[derive(serde::Deserialize, Default)]
struct BoardsSection {
#[serde(default)]
url: Option<String>,
#[serde(default)]
dir: Option<PathBuf>,
}
impl BoardsSection {
/// `None` when the section is absent or entirely empty, which is what makes "this
/// machine uses shared boards" a property of the config rather than of an empty
/// file.
fn option(self) -> Option<MachineConfig> {
let BoardsSection { url, dir } = self;
if url.is_none() && dir.is_none() {
None
} else {
Some(MachineConfig { url, boards_dir: dir })
}
}
}
/// The committed pointer in a project: `.worklane.toml`, naming the board by uuid.
pub struct Pointer {
pub board: String,
}
/// Where the pointer lives, at the project root beside `.worklane`.
pub fn pointer_path(project: &Path) -> PathBuf {
project.join(POINTER_FILE)
}
/// The pointer a project carries, `None` when there is none or it names nothing.
pub fn read_pointer(project: &Path) -> Result<Option<Pointer>> {
let path = pointer_path(project);
let text = match fs::read_to_string(&path) {
Ok(text) => text,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(anyhow!("Could not read the board pointer {}: {error}", path.display()));
}
};
let parsed: PointerFile = toml::from_str(&text).map_err(|error| {
anyhow!("Could not parse the board pointer {}: {error}", path.display())
})?;
Ok(parsed
.worklane
.board
.filter(|board| !board.trim().is_empty())
.map(|board| Pointer { board }))
}
#[derive(serde::Deserialize, Default)]
struct PointerFile {
#[serde(default)]
worklane: PointerSection,
}
#[derive(serde::Deserialize, Default)]
struct PointerSection {
#[serde(default)]
board: Option<String>,
}
/// Write `.worklane.toml` naming `uuid`, creating or replacing the pointer.
///
/// A pointer that already names the same board is left alone: it is a committed file,
/// and rewriting what is already committed writes nothing new.
pub fn write_pointer(project: &Path, uuid: &str) -> Result<PathBuf> {
let path = pointer_path(project);
let text = format!("[worklane]\nboard = \"{uuid}\"\n");
match fs::read_to_string(&path) {
Ok(existing) if existing == text => return Ok(path),
Ok(_) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(anyhow!("Could not read the board pointer {}: {error}", path.display()));
}
}
fs::write(&path, text).map_err(|error| {
anyhow!("Could not write the board pointer {}: {}", path.display(), error)
})?;
Ok(path)
}
/// A board directory's name for a fresh board, `<uuid>_<slug>` after the ticket
/// filename convention.
pub fn board_dir_name(uuid: &str, title: &str) -> String {
format!("{uuid}_{}", slug(title))
}
/// An existing board directory's uuid, the segment before the first underscore.
fn dir_uuid(name: &str) -> &str {
name.split('_').next().unwrap_or(name)
}
/// The board directory in `boards` that `search` names, by uuid prefix, `None` when
/// nothing matches.
///
/// A uuid prefix rather than the full pointer value, so renaming a board's slug breaks
/// no committed pointer, the bargain the ticket filenames already make. Matches only
/// the uuid, never the slug: a directory named `_my-board` carries no uuid to match.
pub fn resolve_board(boards: &Path, search: &str) -> Result<Option<PathBuf>> {
let search = search.to_lowercase();
let matches = match fs::read_dir(boards) {
Ok(entries) => entries
.filter_map(|entry| entry.ok())
.filter(|entry| entry.file_type().is_ok_and(|t| t.is_dir()))
.map(|entry| entry.path())
.filter(|path| {
path.file_name()
.and_then(|name| name.to_str())
.map(|name| dir_uuid(name).to_lowercase().starts_with(&search))
.unwrap_or(false)
})
.collect::<Vec<_>>(),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(anyhow!(
"Could not read the boards directory {}: {error}",
boards.display()
));
}
};
match matches.len() {
0 => Ok(None),
1 => Ok(Some(matches.into_iter().next().unwrap())),
_ => Err(anyhow!(
"'{search}' is ambiguous across {} boards in {}",
matches.len(),
boards.display()
)),
}
}
/// What `init` decided, for the handler to say.
pub enum Init {
/// `.worklane` was already a board for this project, so nothing was written.
AlreadyInitialized(PathBuf),
/// A local `.worklane`, the layout every project had before the shared one.
CreatedLocal(PathBuf),
/// A shared board: pointer written, board directory made, `.worklane` symlinked to
/// it.
CreatedShared {
pointer: PathBuf,
board: PathBuf,
link: PathBuf,
},
/// A deliberate refusal with a reason: the caller looked and decided not to change
/// what a pointer or an existing `.worklane` commits to.
Refused(String),
}
/// The decision table for `init`, one match so no branch can fall through into
/// creating a board.
///
/// `dir` is the canonical project root. `create` is `--create`, the only way to make a
/// board under a pointer that names a missing one.
pub fn decide_init(dir: &Path, create: bool) -> Result<Init> {
let worklane_dir = dir.join(".worklane");
let pointer = read_pointer(dir)?;
match pointer {
// No pointer: this project has never been put on the shared layout.
None => init_no_pointer(dir, &worklane_dir),
Some(pointer) => init_with_pointer(dir, &worklane_dir, &pointer, create),
}
}
fn init_no_pointer(dir: &Path, worklane_dir: &Path) -> Result<Init> {
match classify_worklane(worklane_dir) {
Worklane::Absent => {}
// An existing board of the local layout, or a shared one reached through a link
// whose pointer is missing; either way it is a board already.
Worklane::RealDir => return Ok(Init::AlreadyInitialized(worklane_dir.to_path_buf())),
Worklane::Symlink(_) | Worklane::Dangling(_) => {
return Ok(Init::AlreadyInitialized(worklane_dir.to_path_buf()));
}
Worklane::NotADirectory => {
return Ok(Init::Refused(format!(
"{} is not a directory; refusing to replace what is there.",
worklane_dir.display()
)));
}
}
// The machine config decides the layout. A `[boards]` section means a shared board
// here; none means the local layout, exactly as worklane always created it.
if read_config()?.is_some() {
let boards = boards_dir()?;
let uuid = uuid::Uuid::new_v4().to_string();
let board = boards.join(board_dir_name(&uuid, &project_title(dir)));
fs::create_dir_all(&board).map_err(|error| {
anyhow!("Could not create the board directory {}: {error}", board.display())
})?;
create_board_contents(&board)?;
let link = symlink_board(&board, worklane_dir)?;
let pointer = write_pointer(dir, &uuid)?;
return Ok(Init::CreatedShared { pointer, board, link });
}
Ok(Init::CreatedLocal(create_local(worklane_dir)?))
}
fn init_with_pointer(
dir: &Path,
worklane_dir: &Path,
pointer: &Pointer,
create: bool,
) -> Result<Init> {
let boards = boards_dir()?;
// The boards repo itself must be here: a committed pointer is proof the board
// exists somewhere, and a missing repo is an unsynced machine, not a missing board.
if !boards.is_dir() {
return Ok(Init::Refused(format!(
"The boards directory {} does not exist.\n\
This project names board {} in {},\n\
so its board lives in a boards repo that is not cloned here.\n\
Clone the boards repo (or run `worklane init --create` to make a new one).",
boards.display(),
pointer.board,
pointer_path(dir).display(),
)));
}
let resolved = resolve_board(&boards, &pointer.board)?;
// An existing `.worklane` must not be repointed or walked over. This is where a
// project that predates the shared layout, or one that points at the wrong board,
// is caught.
match classify_worklane(worklane_dir) {
Worklane::Absent => {}
Worklane::RealDir => {
return Ok(Init::Refused(format!(
"{} is a real directory, not the shared board {} names.\n\
This may be a board from before the shared layout, which worklane can \
adopt later (see the migration); refusing to walk over it. Remove it \
first, then run `worklane init` to link the board {} names.",
worklane_dir.display(),
pointer_path(dir).display(),
pointer_path(dir).display(),
)));
}
Worklane::Symlink(target) => {
// A link to exactly the board the pointer names is the layout already in
// place; a link to anything else is not to be repointed.
let board_named = resolved
.as_deref()
.and_then(|board| same(&target, board).then_some(board));
return match board_named {
Some(_) => Ok(Init::AlreadyInitialized(worklane_dir.to_path_buf())),
None => Ok(Init::Refused(format!(
"{} already links to {}, and not to the board {} names.\n\
Refusing to repoint it: changing what a project is on without \
asking is how two machines come to disagree about where the work is.\n\
Remove {} and run `worklane init` again to link {}.",
worklane_dir.display(),
target.display(),
pointer_path(dir).display(),
worklane_dir.display(),
resolved
.map(|p| p.display().to_string())
.unwrap_or_else(|| pointer.board.clone()),
))),
};
}
Worklane::Dangling(target) => {
// A link that resolves nowhere: if it is spelled as the board the pointer
// names — the relative form this tool writes, or the absolute board path —
// the board is out of this machine and the missing-board answer is the
// right one; anything else is not to be replaced without asking. Compared
// lexically, since a dangling link cannot be canonicalized.
let points_at_board = resolved.as_deref().is_some_and(|board| {
let base = worklane_dir.parent().unwrap_or(Path::new(""));
target == relative_path(base, board) || target == board
});
if points_at_board {
return Ok(missing_board(pointer, &boards));
}
return Ok(Init::Refused(format!(
"{} is a link to {}, which does not exist; refusing to replace it \
without asking.",
worklane_dir.display(),
target.display(),
)));
}
Worklane::NotADirectory => {
return Ok(Init::Refused(format!(
"{} is not a directory; refusing to replace what is there.",
worklane_dir.display()
)));
}
}
match resolved {
Some(board) => {
let link = symlink_board(&board, worklane_dir)?;
Ok(Init::CreatedShared {
pointer: pointer_path(dir),
board,
link,
})
}
None => {
if create {
let board = boards.join(board_dir_name(&pointer.board, &project_title(dir)));
fs::create_dir_all(&board).map_err(|error| {
anyhow!("Could not create the board directory {}: {error}", board.display())
})?;
create_board_contents(&board)?;
let link = symlink_board(&board, worklane_dir)?;
Ok(Init::CreatedShared {
pointer: pointer_path(dir),
board,
link,
})
} else {
Ok(missing_board(pointer, &boards))
}
}
}
}
/// The missing-board refusal, shared by the dangling-symlink-to-the-board and the
/// nothing-linking cases, so the board's being out of this machine is told once.
fn missing_board(pointer: &Pointer, boards: &Path) -> Init {
Init::Refused(format!(
"The boards directory {} holds no board for {}.\n\
The boards repo may need pulling; run a fetch there and try again.\n\
To deliberately start a new board under this pointer, run `worklane init --create`.",
boards.display(),
pointer.board,
))
}
/// The slug a newly created board takes: the project directory's name, so a board is
/// named after the project it lives in. Sharing a name keeps a reader looking at the
/// boards directory able to tell which project a board belongs to.
fn project_title(dir: &Path) -> String {
dir.file_name()
.map(|name| name.to_string_lossy().to_string())
.unwrap_or_default()
}
/// Classify an existing `.worklane` entry, distinguishing a real directory from a link
/// that resolves and a link that dangles, so each is answered differently.
enum Worklane {
/// Nothing at that path.
Absent,
/// A directory, not a link: a local board, or one that predates the shared layout.
RealDir,
/// A link that resolves to a directory, carrying the resolved target.
Symlink(PathBuf),
/// A link that resolves to nothing, carrying the target it names.
Dangling(PathBuf),
/// There, and neither a directory nor a link to one.
NotADirectory,
}
/// The four-way answer `init` needs from a `.worklane` path.
fn classify_worklane(path: &Path) -> Worklane {
let entry = match fs::symlink_metadata(path) {
Ok(entry) => entry,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Worklane::Absent,
Err(_) => return Worklane::NotADirectory,
};
if !entry.is_symlink() {
return match entry.is_dir() {
true => Worklane::RealDir,
false => Worklane::NotADirectory,
};
}
let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf());
match fs::metadata(path) {
Ok(resolved) if resolved.is_dir() => {
Worklane::Symlink(fs::canonicalize(path).unwrap_or(path.to_path_buf()))
}
Ok(_) => Worklane::NotADirectory,
Err(_) => Worklane::Dangling(target),
}
}
/// Whether two paths are the same directory, through canonicalization and following
/// links.
fn same(a: &Path, b: &Path) -> bool {
match (fs::canonicalize(a), fs::canonicalize(b)) {
(Ok(a), Ok(b)) => a == b,
_ => false,
}
}
/// Symlink `worklane_dir` to `board`, the one way `.worklane` becomes a board reached
/// through a link.
///
/// The target is made relative to the link's own parent so the link is portable (it
/// uses no home directory path), and the link's parent directory is created since the
/// project may not exist as a directory yet.
fn symlink_board(board: &Path, worklane_dir: &Path) -> Result<PathBuf> {
if let Some(parent) = worklane_dir.parent() {
fs::create_dir_all(parent)
.map_err(|error| anyhow!("Could not create {}: {error}", parent.display()))?;
}
let target = relative_path(worklane_dir.parent().unwrap_or(Path::new("")), board);
make_symlink(&target, worklane_dir)?;
Ok(worklane_dir.to_path_buf())
}
/// A relative path from `base` (a directory) to `target`.
fn relative_path(base: &Path, target: &Path) -> PathBuf {
let base = base.to_path_buf();
let target = target.to_path_buf();
// The common prefix gives how far up `base` the link must climb. When they share a
// root device but no component they have no common ancestor expressible in a
// relative path, and the absolute target is the honest answer.
let common = base
.components()
.zip(target.components())
.take_while(|(a, b)| a == b)
.count();
let mut result = PathBuf::new();
for _ in common..base.components().count() {
result.push("..");
}
for component in target.components().skip(common) {
result.push(component);
}
result
}
/// Create a symlink at `link` to `target`, refusing to replace a different file or link.
fn make_symlink(target: &Path, link: &Path) -> Result<()> {
match fs::symlink_metadata(link) {
// Nothing there: place it.
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(anyhow!("Could not inspect {} before linking: {error}", link.display()));
}
Ok(_) => {
return Err(anyhow!(
"{} already exists; refusing to replace what is there",
link.display()
));
}
}
#[cfg(unix)]
std::os::unix::fs::symlink(target, link).map_err(|error| {
anyhow!("Could not symlink {} to {}: {error}", link.display(), target.display())
})?;
#[cfg(not(unix))]
{
let _ = (target, link);
return Err(anyhow!(
"shared boards need symlinks, which this platform does not support"
));
}
Ok(())
}
/// The local board layout, as `init` always created it: the status directories, the
/// campaigns directory and the tag vocabulary.
///
/// Shared boards call the same helper on their directory. Returns the worklane
/// directory for the message.
fn create_local(worklane_dir: &Path) -> Result<PathBuf> {
fs::create_dir_all(worklane_dir)
.map_err(|error| anyhow!("Could not create {}: {error}", worklane_dir.display()))?;
create_board_contents(worklane_dir)?;
Ok(worklane_dir.to_path_buf())
}
/// The contents every board gets, whatever layout holds it.
fn create_board_contents(worklane_dir: &Path) -> Result<()> {
for folder in crate::util::status_dirs() {
fs::create_dir_all(worklane_dir.join(folder)).map_err(|error| {
anyhow!("Could not create {}: {error}", worklane_dir.join(folder).display())
})?;
}
fs::create_dir_all(crate::campaign::campaigns_dir(worklane_dir)).map_err(|error| {
anyhow!(
"Could not create {}: {error}",
crate::campaign::campaigns_dir(worklane_dir).display()
)
})?;
fs::write(
crate::tag::tags_path(worklane_dir),
crate::tag::TagIndex::default().render(),
)
.map_err(|error| {
anyhow!(
"Could not write {}: {error}",
crate::tag::tags_path(worklane_dir).display()
)
})?;
Ok(())
}
+31 -5
View File
@@ -220,7 +220,11 @@ const PROSE: bool = true;
#[derive(clap::Subcommand)]
pub enum Command {
/// Initialize worklane in the current project
Init,
Init {
/// Create a board even where a committed pointer names one that is not here
#[arg(long)]
create: bool,
},
/// Add a new ticket to the backlog
Add(AddArgs),
@@ -858,14 +862,15 @@ impl ChownArgs {
}
}
/// `append` only offers the sections that hold multiple lines, since appending to a
/// scalar has no meaning.
/// `append` offers the fields something can be added to without disturbing what is
/// already in them: the three sections that hold multiple lines, and Tags, which is a
/// list. Appending to a scalar has no meaning, so there is no `--priority` or `--due`.
#[derive(clap::Args)]
#[command(group(
clap::ArgGroup::new("append_fields")
.required(true)
.multiple(true)
.args(["description", "acceptance", "plan"])
.args(["description", "acceptance", "plan", "tags"])
))]
pub struct AppendArgs {
/// Ticket UUID or title
@@ -882,6 +887,24 @@ pub struct AppendArgs {
/// Add implementation plan steps, numbered on from the last. Repeat the flag
#[arg(short, long, allow_hyphen_values = PROSE)]
pub plan: Vec<String>,
/// Add tags, keeping the ones the ticket already carries. Repeat the flag, or
/// separate them with commas
///
/// `non_empty` rather than the `clearable` that `set --tags` takes. That message
/// names `--clear`, and this command has none: emptying the field is
/// `set --clear tags`, so pointing at a flag that is not here would send the caller
/// looking for it on `append`.
#[arg(short = 'g', long, value_parser = non_empty)]
pub tags: Vec<String>,
/// Only reaches the entry `--tags` writes, since that is the one field of this
/// command's that is logged, exactly as on `set`
#[arg(long, help = ACTOR_HELP)]
pub actor: Option<String>,
#[arg(long, conflicts_with = "actor", help = ACTOR_FROM_GIT_HELP)]
pub actor_from_git: bool,
}
/// `relate` is the only writer of the Relations section, the way `chown` is the only
@@ -1080,6 +1103,9 @@ mod tests {
// 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");
assert_eq!(
seen, 6,
"expected comment, mv, chown, set, append and assign to carry --actor"
);
}
}
+81 -13
View File
@@ -64,12 +64,22 @@ pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
/// Options whose value is a campaign.
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
/// Options whose value is a tag.
/// Options whose value is a tag, as the command that takes it and the flag's long name.
///
/// Its own list rather than a line in the block below, because the values come from a
/// different command: a tag is not an object with an id, so `worklane tags` answers this
/// one where `ls --ids` answers the tickets.
pub const TAG_FLAGS: [&str; 1] = ["tag"];
///
/// Pairs rather than the flat list the other flag lists are, because the two spellings
/// differ: `ls --tag` filters on one and `append --tags` adds them, so a single rule
/// naming both options would tell fish that each command takes the other's flag. One
/// rule per pair instead.
///
/// `add --tags` and `set --tags` are deliberately absent. Both take the *whole* list, so
/// the token being completed is `bug,tui` and fish replaces a token entire: offering one
/// tag there would throw away the ones already typed. `append --tags` is the one where
/// naming a single tag is the ordinary call.
pub const TAG_FLAGS: [(&str, &str); 2] = [("ls", "tag"), ("append", "tags")];
/// Nested commands whose first argument is a tag the board already has.
///
@@ -110,7 +120,16 @@ fn fish_dynamic() -> String {
.collect::<Vec<_>>()
.join("; or ");
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
let tag_flags = flag_list(&TAG_FLAGS);
let tag_flags = TAG_FLAGS
.iter()
.map(|(command, flag)| {
format!(
"complete -c worklane -n '__worklane_command_is {command}' -l {flag} \\\n \
-x -a '(worklane tags | cut -f1,3)'"
)
})
.collect::<Vec<_>>()
.join("\n");
let tag_nested = TAG_NESTED_COMMANDS
.iter()
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
@@ -218,8 +237,10 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
# What is left is the annotation, and a tag the board carries but has never declared has
# none: it is offered with no description at all, which is the near-duplicate the file was
# added to catch. The count used to be the description and said the same thing more weakly.
complete -c worklane -n '__worklane_command_is ls' {tag_flags} \
-x -a '(worklane tags | cut -f1,3)'
#
# One rule per command, from `TAG_FLAGS`: `ls --tag` and `append --tags` are spelled
# differently, so a single rule naming both options would offer each under the other.
{tag_flags}
# And `tags set` names one that is already declared, so it reads the same listing. `tags
# add` has no rule on purpose: it takes a tag the board does not have, so the candidates
@@ -410,14 +431,28 @@ mod tests {
/// about what the fish block is missing, which is a test's question.
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
/// Options taking a whole comma-separated list of tags rather than one.
///
/// `add --tags` and `set --tags` write the field entire, so what is being typed at the
/// cursor is `bug,tui` and fish replaces a token whole: a rule offering one tag there
/// would throw away the ones already in the token. `append --tags` adds to what is
/// there, so a single tag is the ordinary value and it earns a rule. Recorded rather
/// than skipped, for the reason `TAG_NEW_COMMANDS` is: the next `--tags` has to say
/// which of the two it is.
const TAG_LIST_FLAGS: [(&str, &str); 2] = [("add", "tags"), ("set", "tags")];
/// Tags have their own list because their values come from `worklane tags` rather than
/// from a listing of objects, so a second tag-taking option would need that rule and
/// not the campaign one.
///
/// Both spellings are walked, `tag` and `tags`: they are the same object under two
/// argument names, and looking at only the singular is how `set --tags` went years
/// without anybody deciding whether it wanted a rule.
#[test]
fn no_tag_taking_option_is_missing() {
let mut seen = 0;
for (path, arg) in every_argument() {
if arg.get_id().as_str() != "tag" {
if !matches!(arg.get_id().as_str(), "tag" | "tags") {
continue;
}
seen += 1;
@@ -440,13 +475,18 @@ mod tests {
continue;
};
let pair = (name.as_str(), long);
assert!(
TAG_FLAGS.contains(&long),
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
TAG_FLAGS.contains(&pair) || TAG_LIST_FLAGS.contains(&pair),
"`worklane {name} --{long}` takes a tag, so it belongs in TAG_FLAGS if one \
tag is the ordinary value and TAG_LIST_FLAGS if the value is the whole list"
);
}
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
assert_eq!(
seen, 6,
"expected ls --tag, tags add, tags set, add --tags, set --tags and append --tags"
);
}
/// **Every rule naming an option has to say which command it belongs to.** A bare
@@ -472,8 +512,30 @@ mod tests {
fn every_listed_command_is_a_real_subcommand() {
let cli = command();
let known: Vec<&str> = cli.get_subcommands().map(|c| c.get_name()).collect();
for name in TICKET_COMMANDS.iter().chain(TICKET_SECOND_COMMANDS.iter()) {
assert!(known.contains(name), "no such subcommand: {name}");
// Every list that names a top-level command, not only the ticket ones. The others
// were reachable only through the rule counts below, which fail with `expected 3,
// got 4` and name nothing: a stale entry is a `complete` line whose condition never
// matches, so fish offers nothing and says nothing about why.
let top = TICKET_COMMANDS
.iter()
.chain(TICKET_SECOND_COMMANDS.iter())
.chain(CAMPAIGN_COMMANDS.iter())
.copied()
.chain(TAG_FLAGS.iter().map(|(command, _)| *command));
for name in top {
assert!(known.contains(&name), "no such subcommand: {name}");
}
for (parent, child) in CAMPAIGN_NESTED_COMMANDS.iter().chain(TAG_NESTED_COMMANDS.iter()) {
let sub = cli
.find_subcommand(parent)
.unwrap_or_else(|| panic!("no such subcommand: {parent}"));
assert!(
sub.find_subcommand(child).is_some(),
"`worklane {parent}` has no `{child}` subcommand"
);
}
}
@@ -587,10 +649,16 @@ mod tests {
.filter(|line| line.contains("(worklane tags"))
.collect();
// **Hardcoded on purpose, and not derivable from the lists above.** This number is
// what catches an entry naming a command or a flag that does not exist: the walkers
// go clap → list and never see an extra, so a bogus `("bogus", "nope")` in
// `TAG_FLAGS` produces a fourth rule and only this count notices. Writing it as
// `TAG_FLAGS.len() + TAG_NESTED_COMMANDS.len()` would grow with the bogus entry and
// pass, which is the improvement to not make.
assert_eq!(
reading.len(),
2,
"expected the ls --tag rule and the tags set one: {reading:?}"
3,
"expected the ls --tag rule, the append --tags one and the tags set one: {reading:?}"
);
for line in reading {
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
+87 -24
View File
@@ -15,34 +15,26 @@ use crate::install;
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
use crate::util::*;
pub fn cmd_init(start: &Path, sink: &mut Sink) -> Result<()> {
pub fn cmd_init(create: bool, 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() {
sink.writeln(&format!("worklane already initialized in: {}", worklane_dir.display()))?;
return Ok(());
match crate::board::decide_init(&dir, create)? {
crate::board::Init::AlreadyInitialized(worklane_dir) => {
sink.writeln(&format!("worklane already initialized in: {}", worklane_dir.display()))?;
}
crate::board::Init::CreatedLocal(worklane_dir) => {
sink.writeln(&format!("Initialized worklane in: {}", worklane_dir.display()))?;
}
crate::board::Init::CreatedShared { pointer, board, link } => {
sink.writeln(&format!("Initialized shared worklane in: {}", board.display()))?;
sink.writeln(&format!("Board pointer: {}", pointer.display()))?;
sink.writeln(&format!("Linked {} to it", link.display()))?;
}
crate::board::Init::Refused(reason) => {
return Err(anyhow!("{reason}"));
}
}
fs::create_dir_all(&worklane_dir)?;
for folder in status_dirs() {
fs::create_dir_all(worklane_dir.join(folder))?;
}
// Beside the status directories, not among them: a campaign has no status. Created
// here for a new board, and on demand by `campaign add` for a board that predates
// campaigns, which is why `status_dirs()` is untouched.
fs::create_dir_all(campaigns_dir(&worklane_dir))?;
// The tag vocabulary, beside both for the same reason, and written empty rather than
// left for the first `tags add` to make. An empty file explains itself when it is
// opened, which is the point of the preamble, and a board that has one from the start
// has one file shape rather than two. `fs::write` and not `write_then_replace`: the
// directory was made three lines ago, so there is nothing here to truncate.
fs::write(tags_path(&worklane_dir), TagIndex::default().render())?;
sink.writeln(&format!("Initialized worklane in: {}", worklane_dir.display()))?;
Ok(())
}
@@ -1135,12 +1127,83 @@ pub fn cmd_append(args: &AppendArgs, start: &Path, sink: &mut Sink) -> Result<()
changed.push(section.label);
}
// Through `apply`, unlike the sections above: appending a section always adds
// something, and appending a tag the ticket already carries is the no-op this flag
// exists to make free.
if !args.tags.is_empty() {
let next =
set_metadata_field(&content, "Tags", &appended_tags(&content, &args.tags)?, &title)?;
apply(&mut content, &mut changed, "tags", next);
}
// The only way to reach here with nothing to write is a `--tags` the ticket already
// satisfied, since every other field on this command adds or refuses. Reported in the
// words `set` uses for the same answer.
if changed.is_empty() {
report(sink, &[], &title, "Appended to")?;
return Ok(());
}
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
// Tags are logged wherever they change, so the one command that adds to them without
// replacing them logs too. Same shape as `set`'s, down to the before and after being
// read off the field rather than off the flag: what the entry records is where the
// field went, not what this call asked for.
if changed.contains(&"tags") {
write_entry(
&worklane_dir,
&uuid,
Kind::Tags,
&change(
&parse_ticket_field(&original, "Tags"),
&parse_ticket_field(&content, "Tags"),
),
&resolve_actor(args.actor.as_deref(), args.actor_from_git),
"",
)?;
}
report(sink, &changed, &title, "Appended to")?;
Ok(())
}
/// The ticket's tags with the call's merged onto the end, or the refusal for a call that
/// named none.
///
/// A tag the ticket already carries is not added a second time, which is the whole
/// difference from `set --tags`: appending means the caller does not have to know what is
/// there already, so naming one that is reports no change rather than doubling it. New
/// ones go on the end in the order they were given rather than sorted, so the field goes
/// on reading as what was added when.
///
/// The values are split on commas the way the stored field is, so `--tags "bug, tui"`
/// names two tags and matches the two a ticket carrying them already holds. Without that
/// the pair would land as a single tag nothing can filter by, which is what `tag_value`
/// refuses outright for the vocabulary; here it is split instead, because `set --tags`
/// takes the comma form on this same field and refusing it on its counterpart would be a
/// trap.
///
/// A call whose every value comes out blank is refused rather than written, the way
/// [`appended_items`] refuses one: `--tags ","` names nothing, and writing the field back
/// unchanged would report an append that never happened. Emptying the field is
/// `set --clear tags`.
fn appended_tags(content: &str, values: &[String]) -> Result<String> {
let added: Vec<String> = values.iter().flat_map(|value| split_tags(value)).collect();
if added.is_empty() {
return Err(anyhow!("Nothing to append to the tags: every value given was blank"));
}
let mut tags = parse_tags(content);
for tag in added {
if !tags.contains(&tag) {
tags.push(tag);
}
}
Ok(tags.join(", "))
}
/// Record a relation from one ticket to another.
///
/// One side is written and the inverse is derived wherever it is shown. `blocked by`
+100 -69
View File
@@ -1,6 +1,9 @@
use std::path::Path;
use anyhow::Result;
use clap::Parser;
mod board;
mod campaign;
mod clipboard;
mod command;
@@ -50,76 +53,16 @@ fn main() -> Result<()> {
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, &mut sink),
Some(Command::Add(args)) => cmd_add(&args, &start, &mut sink),
Some(Command::Ls(args)) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_ls(&args, &worklane_dir, &mut sink)
}
Some(Command::Show { id }) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_show(&id, &worklane_dir, &mut sink)
}
Some(Command::Mv(args)) => cmd_mv(&args, &start, &mut sink),
Some(Command::Set(args)) => cmd_set(&args, &start, &mut sink),
Some(Command::Append(args)) => cmd_append(&args, &start, &mut sink),
Some(Command::Relate(args)) => cmd_relate(&args, &start, &mut sink),
Some(Command::Chown(args)) => cmd_chown(&args, &start, &mut sink),
Some(Command::Check(args)) => cmd_check(&args, true, &start, &mut sink),
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start, &mut sink),
Some(Command::Comment {
ticket,
body,
actor,
actor_from_git,
}) => cmd_comment(&ticket, &body, &actor, actor_from_git, &start, &mut sink),
Some(Command::Campaign { command }) => match command {
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start, &mut sink),
CampaignCommand::Ls { ids } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_ls(&worklane_dir, ids, &mut sink)
}
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start, &mut sink),
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start, &mut sink),
CampaignCommand::Show { campaign } => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_campaign_show(&campaign, &worklane_dir, &mut sink)
}
},
Some(Command::Assign {
campaign,
ticket,
actor,
actor_from_git,
}) => cmd_assign(&campaign, &ticket, &actor, actor_from_git, &start, &mut 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 {
None | Some(TagCommand::Ls) => {
let worklane_dir = find_worklane_dir(&start)?;
cmd_tags(&worklane_dir, &mut sink)
}
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start, &mut sink),
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start, &mut 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, 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, &mut 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, &mut sink),
Some(command) => dispatch(&command, &start, &mut sink),
};
// The board (and every handler) own their own writing, so flush what the last one
@@ -128,6 +71,93 @@ fn main() -> Result<()> {
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 { create } => cmd_init(*create, 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)
}
Command::Show { id } => {
let worklane_dir = find_worklane_dir(start)?;
cmd_show(id, &worklane_dir, sink)
}
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,
body,
actor,
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, sink)
}
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, sink)
}
},
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.
Command::Tags { command } => match command {
None | Some(TagCommand::Ls) => {
let worklane_dir = find_worklane_dir(start)?;
cmd_tags(&worklane_dir, sink)
}
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.
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.
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.
Command::InstallTool { force, print } => cmd_install_tool(*force, *print, sink),
}
}
// ---------------------------------------------------------------------- tui --
/// Restore the terminal whatever happens.
@@ -222,9 +252,10 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
// 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. No screen, because nothing it does measures the board yet. The
// rule is `Board::prompt_key`, where a test can reach it.
if board.prompt_key(key) {
// 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;
}
+1341 -86
View File
File diff suppressed because it is too large Load Diff
+195 -26
View File
@@ -303,6 +303,42 @@ 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
@@ -332,7 +368,10 @@ impl<'a> Sink<'a> {
/// An in-memory buffer, plain, for a test or a caller that colours the text
/// itself.
#[allow(dead_code)]
///
/// 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),
@@ -1569,6 +1608,16 @@ pub fn parse_tags(content: &str) -> Vec<String> {
return Vec::new();
}
split_tags(&value)
}
/// The tags in one comma-separated value, trimmed and without the empty ones.
///
/// Split out of [`parse_tags`] because a value typed on the command line is separated the
/// same way the stored field is: `append --tags "bug, tui"` names two tags, and merging
/// that into what a ticket already carries has to see two or it stores the pair as one
/// tag and adds it again on the next call.
pub fn split_tags(value: &str) -> Vec<String> {
value
.split(',')
.map(str::trim)
@@ -3274,7 +3323,8 @@ impl TicketItem {
/// A slot per status rather than a lookup by field name, so a fifth status carrying
/// a stamp is a compile error here the way it is in [`Status::stamp_field`].
/// Backlog has none: nothing stamps it, and `Created At` is not an entry time, so
/// every ticket in that column answers `None` and the whole order is the fallback.
/// every ticket in that column answers `None` and [`TicketItem::due_key`] is what
/// orders it instead.
fn entry_stamp(&self, status: Status) -> Option<&str> {
match status {
Status::Backlog => None,
@@ -3284,6 +3334,22 @@ impl TicketItem {
Status::Discarded => self.discarded_on.as_deref(),
}
}
/// The date the ticket is due, or `None` for one carrying nothing orderable.
///
/// What the backlog is sorted on, standing in for the entry stamp the column does
/// not have. `YYYY-MM-DD` only, so lexicographic order is chronological order and
/// the comparison stays a string comparison like the stamps'. `--due` has refused
/// anything else since daa0e79, and [`due_date`] cuts a datetime written before
/// that, or by hand, back to its date.
///
/// Free text answers `None` rather than sorting on its spelling. A due nobody can
/// place on a calendar is unknown, the same reading a missing stamp gets, and
/// unknown must not claim a place in a queue ordered by time.
fn due_key(&self) -> Option<&str> {
let date = due_date(&self.due);
is_ymd(date).then_some(date)
}
}
/// The stamp a ticket carries for a status, or `None` for one it has not reached.
@@ -3489,8 +3555,7 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
Ok(items)
}
/// The order the backlog is read in, and the tiebreak every other column falls back to:
/// priority first, title second.
/// The tiebreak every column falls back to: priority first, title second.
///
/// Named and exported because the board's All tab merges several boards' columns into
/// one and has to land in one order. A merge sorted a second way would put a p1 below a
@@ -3505,36 +3570,46 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
/// The order one status column is read in, keyed on the status.
///
/// Priority is the clock in the backlog, and that column keeps exactly the order it has
/// always printed. Past the backlog the question changes: committed asks what has waited
/// longest, reviewing what was handed over first, done what just landed. The head of
/// every column is therefore what the reader acts on next, which is ascending by entry
/// stamp in committed and reviewing and descending in done and discarded, the way a
/// changelog reads.
/// Every column asks the same question, what the reader acts on next, and answers it
/// with the one date it has. Committed asks what has waited longest, reviewing what was
/// handed over first, done what just landed: ascending by entry stamp in committed and
/// reviewing, descending in done and discarded, the way a changelog reads. The backlog
/// carries no entry stamp, so what heads it is the date the work is wanted by, soonest
/// first. Priority ran that column alone until then, which sat a p1 nobody had promised
/// above a p3 due tomorrow.
///
/// A ticket with no stamp sinks below every stamped one in its column. A missing time is
/// unknown, not ancient, and unknown must not claim the head of a queue ahead of a wait
/// somebody can point at. Reading absence as the epoch would come free from the string
/// comparison and put every legacy ticket first on data nothing verified.
/// A ticket with no date sinks below every dated one in its column, whether that date is
/// a stamp or a due. A missing time is unknown, not ancient, and unknown must not claim
/// the head of a queue ahead of a deadline somebody can point at. Reading absence as the
/// epoch would come free from the string comparison and put every legacy ticket first on
/// data nothing verified.
///
/// The comparison is a string comparison. The stamp format is `%Y-%m-%d %H:%M:%S`, where
/// lexicographic order is chronological order, the same property `Due` already relies
/// on, so there is no date parsing at sort time. Equal stamps happen, `mv` writes whole
/// seconds, and they fall through to priority and title like everything else.
/// The comparison is a string comparison. The stamp format is `%Y-%m-%d %H:%M:%S` and a
/// due is `%Y-%m-%d`, both of which order lexicographically the way they order
/// chronologically, so there is no date parsing at sort time. Equal dates happen, `mv`
/// writes whole seconds and a due has no time at all, and they fall through to priority
/// and title like everything else.
pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
let by_stamp = match (a.entry_stamp(status), b.entry_stamp(status)) {
// One pair, so the rules below are written once. Which date a column is keyed on is
// the only thing that changes with the status.
let (left, right) = match status {
Status::Backlog => (a.due_key(), b.due_key()),
_ => (a.entry_stamp(status), b.entry_stamp(status)),
};
let by_date = match (left, right) {
(Some(left), Some(right)) => match status {
Status::Done | Status::Discarded => right.cmp(left),
_ => left.cmp(right),
},
(Some(_), None) => std::cmp::Ordering::Less,
(None, Some(_)) => std::cmp::Ordering::Greater,
// Both unstamped, which is every ticket in the backlog: the fallback is the
// whole order there rather than a tiebreak.
// Neither carries one, which is every undated ticket in the backlog: the
// fallback is the whole order between them rather than a tiebreak.
(None, None) => std::cmp::Ordering::Equal,
};
by_stamp.then_with(|| by_priority_then_title(a, b))
by_date.then_with(|| by_priority_then_title(a, b))
}
/// The environment variable that keeps a test's fixture directory on disk.
@@ -4600,6 +4675,16 @@ mod tests {
}
}
/// A listed ticket carrying a due value, which is what the backlog column is ordered
/// by. Built off [`listed`] rather than beside it, so a field added to `TicketItem`
/// is still filled in one place.
fn due_on(title: &str, level: u8, status: Status, due: &str) -> TicketItem {
TicketItem {
due: due.to_string(),
..listed(title, level, status, None)
}
}
/// Sorted the way the column is read, titles out, so a case reads as the order it
/// asserts rather than as a pair of comparisons.
fn ordered(status: Status, mut items: Vec<TicketItem>) -> Vec<String> {
@@ -4607,11 +4692,11 @@ mod tests {
items.into_iter().map(|item| item.title).collect()
}
/// The backlog is the one column priority still governs, and it prints exactly what
/// it always has: the stamps a ticket carries from an earlier trip through the flow
/// do not reach it, because backlog has no stamp of its own to sort on.
/// Undated backlog tickets keep exactly the order the column always printed: the
/// stamps a ticket carries from an earlier trip through the flow do not reach it,
/// because backlog has no stamp of its own to sort on.
#[test]
fn the_backlog_keeps_priority_then_title() {
fn undated_backlog_tickets_keep_priority_then_title() {
let items = vec![
listed("zebra", 5, Status::Backlog, None),
listed("alpha", 1, Status::Backlog, None),
@@ -4621,6 +4706,90 @@ mod tests {
assert_eq!(ordered(Status::Backlog, items), ["alpha", "beta", "zebra"]);
}
/// The due date is the backlog's clock, so the soonest deadline heads the column the
/// way the oldest wait heads committed. Priority is deliberately inverted against the
/// dates here: a p1 due last is still listed last.
#[test]
fn the_backlog_lists_the_soonest_due_date_first() {
let items = vec![
listed("undated", 1, Status::Backlog, None),
due_on("last", 1, Status::Backlog, "2026-09-03"),
due_on("first", 5, Status::Backlog, "2026-09-01"),
due_on("middle", 3, Status::Backlog, "2026-09-02"),
];
assert_eq!(ordered(Status::Backlog, items), ["first", "middle", "last", "undated"]);
}
/// A due nobody promised must not outrank one somebody did, whatever the priorities
/// say. This is the case the column got wrong before: the p1 sat on top.
#[test]
fn a_dated_backlog_ticket_sorts_above_an_undated_one_of_any_priority() {
let items = vec![
listed("undated", 1, Status::Backlog, None),
due_on("dated", 5, Status::Backlog, "2026-09-01"),
];
assert_eq!(ordered(Status::Backlog, items), ["dated", "undated"]);
}
/// A due carries no time, so two tickets wanted on the same day is the common case
/// rather than the rare one, and it falls through to priority and title.
#[test]
fn backlog_tickets_sharing_a_due_date_fall_back_to_priority_then_title() {
let same = "2026-09-01";
let items = vec![
due_on("zebra", 1, Status::Backlog, same),
due_on("beta", 3, Status::Backlog, same),
due_on("alpha", 3, Status::Backlog, same),
];
assert_eq!(ordered(Status::Backlog, items), ["zebra", "alpha", "beta"]);
}
/// `--due` has taken `YYYY-MM-DD` and nothing else since daa0e79, but a file written
/// before that or by hand can hold a datetime or free text. The datetime sorts on the
/// date inside it; the free text is unknown rather than a date, and sinks with the
/// unset ones instead of sorting on its spelling.
#[test]
fn a_backlog_due_that_is_not_a_plain_date_sorts_on_what_can_be_read_from_it() {
let items = vec![
due_on("prose", 1, Status::Backlog, "next friday"),
due_on("unset", 1, Status::Backlog, NOT_SET),
due_on("datetime", 5, Status::Backlog, "2026-09-01 09:30:00"),
];
assert_eq!(ordered(Status::Backlog, items), ["datetime", "prose", "unset"]);
}
/// The due is the backlog's clock and only the backlog's. Past it the entry stamp is
/// the question, and a deadline set on a committed ticket does not reorder the queue
/// of what has waited longest.
#[test]
fn a_due_date_does_not_reorder_a_column_past_the_backlog() {
for status in [
Status::Committed,
Status::Reviewing,
Status::Done,
Status::Discarded,
] {
let soon = TicketItem {
due: "2026-09-01".to_string(),
..listed("soon", 1, status, Some("2026-08-02 09:00:00"))
};
let items = vec![
soon,
listed("later", 1, status, Some("2026-08-01 09:00:00")),
];
let expected = match status {
Status::Done | Status::Discarded => ["soon", "later"],
_ => ["later", "soon"],
};
assert_eq!(ordered(status, items), expected, "{status:?}");
}
}
/// Committed and reviewing are queues: the head is what has waited longest, which is
/// where the reader picks next from.
#[test]
+11 -1
View File
@@ -247,7 +247,17 @@ fn nothing_is_created_without_a_title() {
fn init_creates_the_campaigns_directory() {
let temp = TempDir::new().unwrap();
let out = run(&temp, &["init"]);
// Isolated HOME and XDG so `init` cannot decide on a real machine's boards config:
// the board has to be local no matter whose machine runs the suite.
let mut init = Command::cargo_bin(BIN_NAME).unwrap();
let out = init
.current_dir(temp.path())
.env("HOME", temp.path())
.env("XDG_CONFIG_HOME", temp.path().join("config"))
.env("XDG_DATA_HOME", temp.path().join("data"))
.arg("init")
.output()
.unwrap();
assert!(out.status.success(), "{}", stderr(&out));
assert!(temp.child(".worklane").child("campaigns").path().is_dir());
+234
View File
@@ -68,6 +68,240 @@ fn fish_is_offered_every_status() {
assert!(out.contains("-a 'backlog committed reviewing done discarded' -d status"));
}
/// A board holding one ticket and one tag, for the rules whose values come off a board.
///
/// Returned with the ticket's id and the tag, since the assertions are that those exact
/// strings are what fish offers.
fn board() -> (assert_fs::TempDir, String, String) {
let temp = assert_fs::TempDir::new().unwrap();
let mut init = Command::cargo_bin(BIN_NAME).unwrap();
// Isolated HOME and XDG so `init` cannot decide on a real machine's boards config:
// the board has to be local no matter whose machine runs the suite.
init.current_dir(temp.path())
.env("HOME", temp.path())
.env("XDG_CONFIG_HOME", temp.path().join("config"))
.env("XDG_DATA_HOME", temp.path().join("data"))
.arg("init")
.assert()
.success();
let mut add = Command::cargo_bin(BIN_NAME).unwrap();
add.current_dir(temp.path())
.args(["add", "--title", "A ticket to complete", "--tags", "atag"])
.assert()
.success();
let mut ls = Command::cargo_bin(BIN_NAME).unwrap();
let listed = ls
.current_dir(temp.path())
.args(["ls", "--ids"])
.assert()
.success();
let listed = String::from_utf8(listed.get_output().stdout.clone()).unwrap();
let id = listed.split('\t').next().unwrap().trim().to_string();
(temp, id, "atag".to_string())
}
/// What fish would actually offer for a half-typed line, or `None` when fish is absent.
///
/// `complete -C` is fish's own answer to "what are the candidates here", so this asks the
/// question a person at a prompt asks rather than searching the script for the rule that
/// ought to produce the answer. Each candidate is a name and, after a tab, its description.
///
/// **The shell is pointed at the binary under test and stood in a real board**, which is
/// what makes the dynamic half testable at all: its rules are command substitutions calling
/// `worklane ls --ids` and `worklane tags`, so with no board and no binary they return
/// nothing and every assertion about them would pass on an empty answer. The directory of
/// `CARGO_BIN_EXE_worklane` goes on the front of PATH so the substitution runs this build
/// rather than whatever is installed.
///
/// **`fish_complete_path` is emptied first, and without that line this test cannot fail.**
/// `complete -C` autoloads completions for the command it is asked about, so a developer
/// who has ever run `worklane completions fish > ~/.config/fish/completions/worklane.fish`
/// gets that file merged into the answer. It was written by some earlier version of this
/// binary and answers for whatever the rules used to be: the first draft of this test
/// passed against a deliberately broken scope because the installed copy still had the
/// working one. Emptying the path is what makes the sourced script the only source.
fn candidates(board: &assert_fs::TempDir, line: &str) -> Option<Vec<String>> {
// Beside the board rather than in it: a rule that fires nothing falls back to listing
// the directory, and a script sitting in there would appear among the candidates and
// read like an answer.
let holder = assert_fs::TempDir::new().unwrap();
let path = holder.path().join("worklane.fish");
std::fs::write(&path, script("fish")).unwrap();
let bin_dir = std::path::Path::new(BIN_NAME).parent().unwrap();
let inherited = std::env::var("PATH").unwrap_or_default();
let asked = std::process::Command::new("fish")
.current_dir(board.path())
.env("PATH", format!("{}:{inherited}", bin_dir.display()))
.arg("-c")
.arg(format!(
"set fish_complete_path; source {}; complete -C '{line}'",
path.display()
))
.output();
match asked {
Ok(out) => Some(
String::from_utf8_lossy(&out.stdout)
.lines()
.map(str::to_string)
.collect(),
),
Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
Err(err) => panic!("could not run fish: {err}"),
}
}
/// The name half of a candidate, dropping the description fish takes after the tab.
fn names(candidates: &[String]) -> Vec<&str> {
candidates
.iter()
.map(|line| line.split('\t').next().unwrap_or(line))
.collect()
}
/// **Ask fish what it offers, instead of asserting that the rule that should make it
/// offer that is in the file.**
///
/// Every other test here reads the script as text, which cannot tell a rule that fires
/// from one whose condition stopped matching. That is how a completion actually breaks:
/// the clap definition moves, a list or a `__worklane_command_is` scope no longer names
/// anything, and the rule sits in the file offering nothing. Loading it into a real fish
/// and asking for the candidates is the only check that can see the difference.
///
/// **Asserting the values, not only the names, is the point.** clap emits every option's
/// name on its own, so `--tags` and `--blocked-by` are offered whether or not the dynamic
/// half loaded: an assertion that they appear passes with every hand-written rule deleted.
/// What those rules add is the candidates *after* the flag, and that is what is pinned
/// here, against the board `board()` puts under the shell.
///
/// Descriptions are read off deliberately and not asserted: every option carrying a
/// hand-written rule currently loses the help text clap gave it, which is its own ticket
/// rather than something to pin as correct here.
///
/// **Skipped when fish is not on PATH, and it says so.** There is no CI here and fish is
/// the shell this tool is written for, so failing a machine that never had it would be a
/// guard nobody could satisfy. A missing fish means the check did not run, not that it
/// passed.
#[test]
fn fish_offers_the_commands_the_statuses_and_the_values() {
let (temp, id, tag) = board();
let Some(commands) = candidates(&temp, "worklane ") else {
eprintln!("skipped: fish is not on PATH, so nothing asked it for candidates");
return;
};
for command in [
"add", "ls", "show", "mv", "set", "append", "relate", "campaign",
] {
assert!(
names(&commands).contains(&command),
"`worklane <TAB>` never offers {command}"
);
}
// The `ls` status positional, which clap emits nothing for, so this answer comes from
// the dynamic half alone and an empty one means that half stopped loading.
let statuses = candidates(&temp, "worklane ls ").unwrap();
for status in ["backlog", "committed", "reviewing", "done", "discarded"] {
assert!(
names(&statuses).contains(&status),
"`worklane ls <TAB>` never offers {status}"
);
}
let shells = candidates(&temp, "worklane completions ").unwrap();
for shell in ["fish", "bash", "zsh"] {
assert!(
names(&shells).contains(&shell),
"`worklane completions <TAB>` never offers {shell}"
);
}
// Every rule whose values come off the board, one per list it is generated from.
let ticket_value = [
("worklane show ", "TICKET_COMMANDS"),
("worklane chown alice ", "TICKET_SECOND_COMMANDS"),
("worklane relate --blocked-by ", "TICKET_FLAGS"),
("worklane chown --clear ", "the chown --clear rule"),
];
for (line, list) in ticket_value {
let offered = candidates(&temp, line).unwrap();
assert!(
names(&offered).contains(&id.as_str()),
"`{line}<TAB>` never offers the one ticket on the board, so {list} is not reaching it: {offered:?}"
);
}
let tag_value = [
("worklane ls --tag ", "TAG_FLAGS"),
("worklane append --tags ", "TAG_FLAGS"),
("worklane tags set ", "TAG_NESTED_COMMANDS"),
];
for (line, list) in tag_value {
let offered = candidates(&temp, line).unwrap();
assert!(
names(&offered).contains(&tag.as_str()),
"`{line}<TAB>` never offers the one tag on the board, so {list} is not reaching it: {offered:?}"
);
}
}
/// **The script is handed to fish, which parses it without running it.**
///
/// The fish half is a hand-written `format!` string carrying single quotes, command
/// substitutions and backslash line continuations, and every text assertion in this file
/// is a `contains`, which a broken script satisfies exactly as well as a correct one.
/// `--no-execute` is the parse without the run.
///
/// **What it catches is a script that does not parse**: quotes still open at the end of
/// the file, an unclosed block. That is narrower than it sounds and the limit is worth
/// writing down, because it was measured rather than assumed. An apostrophe interpolated
/// into a `-d` description partway down the file re-balances against the next quote and
/// parses, corrupting every rule in between while this test passes; the same apostrophe in
/// the *last* rule reaches the end unbalanced and is caught. So this is a floor, not an
/// oracle, and `fish_offers_the_commands_the_statuses_and_the_flags` is the one that reads
/// what the rules actually do.
///
/// Only fish, because only fish gets a hand-written half. What the other four shells are
/// given is clap's output whole, which `no_other_shell_gets_the_fish_half` pins, so a
/// syntax error there would be clap's bug and not this repo's to catch.
///
/// **Skipped when fish is not on PATH, and it says so.** The trade is deliberate: there is
/// no CI here and fish is the shell this tool is written for, so failing a machine that
/// never had it would be a guard nobody could satisfy. A missing fish means the check did
/// not run, not that it passed.
#[test]
fn fish_parses_the_script_it_is_given() {
let temp = assert_fs::TempDir::new().unwrap();
let path = temp.path().join("worklane.fish");
std::fs::write(&path, script("fish")).unwrap();
let parsed = std::process::Command::new("fish")
.arg("--no-execute")
.arg(&path)
.output();
let out = match parsed {
Ok(out) => out,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
eprintln!("skipped: fish is not on PATH, so the generated script went unparsed");
return;
}
Err(err) => panic!("could not run fish: {err}"),
};
assert!(
out.status.success(),
"fish refuses the script `worklane completions fish` writes:\n{}",
String::from_utf8_lossy(&out.stderr)
);
}
#[test]
fn an_unknown_shell_is_a_usage_error() {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
+359
View File
@@ -0,0 +1,359 @@
//! `worklane init` and the shared-board decision table (c6a61b4).
//!
//! A project is on one of two layouts: the local `.worklane` directory every project
//! always had, or the shared one where the project carries a committed `.worklane.toml`,
//! the board lives in a machine-level boards directory, and `.worklane` is a symlink
//! into it. The machine config decides the default, and the pointer decides where the
//! project already is. The tests below walk the whole table: one per row, the three
//! symlink states, and the standalone path.
//!
//! Every test runs on an isolated machine: `HOME` and the XDG variables point into the
//! temp directory, so the suite can never read or write a real config or boards
//! directory, and a `find_worklane_dir` walk from the project can never climb into one.
use assert_cmd::Command;
use assert_fs::TempDir;
use assert_fs::fixture::{PathChild, PathCreateDir};
use std::fs;
use std::path::{Path, PathBuf};
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
/// A project with no pointer and no board, ready for `init` to decide on.
fn project(temp: &TempDir) -> PathBuf {
temp.child("project").create_dir_all().unwrap();
temp.child("project").path().to_path_buf()
}
fn run(project: &Path, machine: &TempDir, args: &[&str]) -> std::process::Output {
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(project)
.env("HOME", machine.path())
.env("XDG_CONFIG_HOME", machine.path().join(".config"))
.env("XDG_DATA_HOME", machine.path().join(".local/share"))
.args(args);
cmd.assert().get_output().clone()
}
fn stdout(out: &std::process::Output) -> String {
String::from_utf8_lossy(&out.stdout).to_string()
}
fn stderr(out: &std::process::Output) -> String {
String::from_utf8_lossy(&out.stderr).to_string()
}
/// The boards directory of a machine, under its data dir.
fn boards_dir(machine: &TempDir) -> PathBuf {
machine.path().join(".local/share/worklane/boards")
}
/// The board a pointer names when the machine holds it.
fn board_path(machine: &TempDir, uuid: &str, slug: &str) -> PathBuf {
boards_dir(machine).join(format!("{uuid}_{slug}"))
}
/// The machine config, without which a no-pointer project stays on the local layout.
///
/// Carries only the boards repo url; the boards directory defaults under the machine's
/// data dir, which is where these tests put it.
fn with_boards_config(machine: &TempDir) {
let config = machine.path().join(".config/worklane/config.toml");
fs::create_dir_all(config.parent().unwrap()).unwrap();
fs::write(config, "[boards]\nurl = \"git@example:worklane/boards\"\n").unwrap();
}
/// The committed pointer naming a board by uuid. This is the only thing that puts a
/// project on the shared layout.
fn write_pointer(project: &Path, uuid: &str) {
fs::write(project.join(".worklane.toml"), format!("[worklane]\nboard = \"{uuid}\"\n")).unwrap();
}
/// A board directory in the machine's boards repo, named `<uuid>_<slug>`.
fn with_board(machine: &TempDir, uuid: &str, slug: &str) -> PathBuf {
let board = board_path(machine, uuid, slug);
fs::create_dir_all(&board).unwrap();
board
}
/// The relative spelling init gives a `.worklane` symlink, used to build the states a
/// project can already be in.
fn link_target(project: &Path, board: &Path) -> String {
let base = project;
let common = base
.components()
.zip(board.components())
.take_while(|(a, b)| a == b)
.count();
let mut up = String::new();
for _ in common..base.components().count() {
up.push_str("../");
}
let mut rest = String::new();
for component in board.components().skip(common) {
rest.push_str(&component.as_os_str().to_string_lossy());
rest.push('/');
}
format!("{up}{rest}").trim_end_matches('/').to_string()
}
fn symlink_to(project: &Path, target: &str) {
std::os::unix::fs::symlink(target, project.join(".worklane")).unwrap();
}
fn boards_of(machine: &TempDir) -> Vec<PathBuf> {
fs::read_dir(boards_dir(machine))
.unwrap()
.map(|entry| entry.unwrap().path())
.collect()
}
/// The standalone path, and the reason it has to stay: every project written before the
/// shared layout existed, and every project whose machine has no boards config, must
/// still get exactly the board `init` always made.
#[test]
fn no_pointer_no_config_and_no_boards_repo_makes_a_local_board() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
let out = run(&project, &machine, &["init"]);
assert!(out.status.success(), "{}", stderr(&out));
assert_eq!(
stdout(&out),
format!("Initialized worklane in: {}\n", project.join(".worklane").display())
);
assert!(
fs::symlink_metadata(project.join(".worklane")).unwrap().is_dir(),
".worklane must be a real directory"
);
assert!(!project.join(".worklane.toml").exists(), "no pointer on a local board");
for dir in [
"backlog",
"committed",
"reviewing",
"done",
"discarded",
"campaigns",
] {
assert!(project.join(".worklane").join(dir).is_dir(), "local board missing {dir}");
}
}
/// The pointer is committed and carries only the board by uuid, nowhere for a home
/// directory or a server address to hide.
#[test]
fn a_shared_init_commits_a_pointer_carrying_only_the_uuid() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
let out = run(&project, &machine, &["init"]);
assert!(out.status.success(), "{}", stderr(&out));
let output = stdout(&out);
assert!(output.contains("Initialized shared worklane in: "), "{output}");
assert!(output.contains("Board pointer: "), "{output}");
assert!(
output.contains(&format!("Linked {} to it", project.join(".worklane").display())),
"{output}"
);
let board = output
.lines()
.next()
.unwrap()
.trim_start_matches("Initialized shared worklane in: ")
.to_string();
let uuid = Path::new(&board)
.file_name()
.unwrap()
.to_str()
.unwrap()
.split('_')
.next()
.unwrap();
let pointer = fs::read_to_string(project.join(".worklane.toml")).unwrap();
assert_eq!(pointer, format!("[worklane]\nboard = \"{uuid}\"\n"));
assert!(
!pointer.contains(machine.path().to_str().unwrap()),
"no home path in the pointer"
);
assert!(!pointer.contains("git@"), "no server address in the pointer");
}
/// A pointer whose board is present is the state a fresh clone is in: `.worklane` is
/// missing and nothing else is. init links it and creates nothing.
#[test]
fn pointer_with_the_board_present_symlinks_it_and_creates_nothing() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
let board = with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "project");
let before = fs::read_to_string(project.join(".worklane.toml")).unwrap();
let out = run(&project, &machine, &["init"]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(
stdout(&out).contains(&format!("Linked {} to it", project.join(".worklane").display()))
);
assert_eq!(
fs::canonicalize(project.join(".worklane")).unwrap(),
fs::canonicalize(&board).unwrap()
);
assert_eq!(fs::read_to_string(project.join(".worklane.toml")).unwrap(), before);
assert_eq!(boards_of(&machine).len(), 1, "no second board was created");
}
/// A pointer whose board is absent is an unsynced machine, and creating a second board
/// there is the worst outcome in the design. init refuses, and `--create` is the only
/// way to make one.
#[test]
fn pointer_with_the_board_absent_refuses_and_create_is_the_only_way() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
write_pointer(&project, "abcd5678-abcd-4bcd-abcd-abcdabcdabcd");
with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "other");
let out = run(&project, &machine, &["init"]);
assert!(!out.status.success());
let err = stderr(&out);
assert!(
err.contains("holds no board for abcd5678-abcd-4bcd-abcd-abcdabcdabcd."),
"{err}"
);
assert!(err.contains("`worklane init --create`"), "{err}");
assert!(!project.join(".worklane").exists(), "nothing was linked");
assert_eq!(boards_of(&machine).len(), 1, "no board was created");
let out = run(&project, &machine, &["init", "--create"]);
assert!(out.status.success(), "{}", stderr(&out));
assert_eq!(
fs::canonicalize(project.join(".worklane")).unwrap(),
fs::canonicalize(board_path(&machine, "abcd5678-abcd-4bcd-abcd-abcdabcdabcd", "project"))
.unwrap()
);
}
/// The boards directory itself is gone: that is an uncloned boards repo, not a missing
/// board, and the two must be told apart.
#[test]
fn boards_repo_missing_is_said_as_such() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
let out = run(&project, &machine, &["init"]);
assert!(!out.status.success());
let err = stderr(&out);
assert!(err.contains("does not exist"), "{err}");
assert!(err.contains("boards repo that is not cloned here"), "{err}");
}
/// The correct symlink in place is the layout already there: init reports no change and
/// writes nothing.
#[test]
fn correct_symlink_already_in_place_reports_no_change() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
let board = with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "project");
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
symlink_to(&project, &link_target(&project, &board));
let before = fs::read_to_string(project.join(".worklane.toml")).unwrap();
let out = run(&project, &machine, &["init"]);
assert!(out.status.success(), "{}", stderr(&out));
assert!(stdout(&out).starts_with("worklane already initialized in: "));
assert_eq!(fs::read_to_string(project.join(".worklane.toml")).unwrap(), before);
assert_eq!(boards_of(&machine).len(), 1, "nothing was written");
}
/// A symlink pointing at a different board is a project on the wrong board, and changing
/// what a project is on without asking is how two machines disagree about the work.
#[test]
fn symlink_to_a_different_board_refuses_rather_than_repointing() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "project");
let other = with_board(&machine, "99999999-9999-4999-8999-999999999999", "other");
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
let other_target = link_target(&project, &other);
symlink_to(&project, &other_target);
let out = run(&project, &machine, &["init"]);
assert!(!out.status.success());
let err = stderr(&out);
assert!(err.contains("already links to"), "{err}");
assert!(err.contains("not to the board"), "{err}");
assert_eq!(
fs::read_link(project.join(".worklane")).unwrap(),
PathBuf::from(&other_target)
);
}
/// A symlink that resolves to nothing is neither the layout init places nor a board: it
/// is not replaced without asking.
#[test]
fn symlink_that_dangles_is_not_replaced() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "project");
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
symlink_to(&project, "nowhere-anyone-knows");
let out = run(&project, &machine, &["init"]);
assert!(!out.status.success());
let err = stderr(&out);
assert!(err.contains("nowhere-anyone-knows, which does not exist"), "{err}");
assert_eq!(
fs::read_link(project.join(".worklane")).unwrap(),
PathBuf::from("nowhere-anyone-knows")
);
}
/// A real `.worklane` directory under a pointer is a board from before the shared
/// layout, and it is never walked over; the refusal names the adopt path.
#[test]
fn real_worklane_directory_under_a_pointer_refuses_and_names_the_adopt_path() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "project");
fs::create_dir_all(project.join(".worklane").join("backlog")).unwrap();
fs::write(project.join(".worklane").join("backlog").join("b.md"), "# anything\n").unwrap();
let out = run(&project, &machine, &["init"]);
assert!(!out.status.success());
let err = stderr(&out);
assert!(err.contains("is a real directory"), "{err}");
assert!(err.contains("adopt"), "{err}");
assert!(
project.join(".worklane").join("backlog").join("b.md").is_file(),
"the pre-existing board was left intact"
);
}
/// The slug, and only the slug, may change: resolution is a uuid prefix match, so
/// renaming a board breaks no committed pointer.
#[test]
fn renaming_a_board_slug_breaks_no_pointer() {
let machine = TempDir::new().unwrap();
let project = project(&machine);
with_boards_config(&machine);
write_pointer(&project, "12345678-1234-1234-1234-1234567890ab");
let renamed = with_board(&machine, "12345678-1234-1234-1234-1234567890ab", "new-name");
let out = run(&project, &machine, &["init"]);
assert!(out.status.success(), "{}", stderr(&out));
assert_eq!(
fs::canonicalize(project.join(".worklane")).unwrap(),
fs::canonicalize(&renamed).unwrap()
);
}
+81 -2
View File
@@ -114,14 +114,16 @@ fn ls_with_invalid_status_fails() {
.failure();
}
/// Title is the last tiebreak, so the three share a due date and a priority: anything
/// else here would be testing the due order instead, which has its own case.
#[test]
fn ls_listed_tickets_sorted_alphabetically() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog", "Zebra", "alice", "2026-06-01");
create_ticket(&worklane, "backlog", "Apple", "bob", "2026-07-01");
create_ticket(&worklane, "backlog", "Mango", "charlie", "2026-08-01");
create_ticket(&worklane, "backlog", "Apple", "bob", "2026-06-01");
create_ticket(&worklane, "backlog", "Mango", "charlie", "2026-06-01");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path())
@@ -744,6 +746,32 @@ fn create_stamped_ticket(
.unwrap();
}
/// A backlog ticket with the due date that column is ordered by.
///
/// Backlog only, the way [`create_stamped_ticket`] is one status at a time: the due is
/// what stands in for an entry stamp in the one column that has none, and `_Not set_`
/// passed here is the undated case rather than a separate helper.
fn create_due_ticket(
worklane_dir: &std::path::Path,
title: &str,
uuid: &str,
priority: &str,
due: &str,
) {
let body = format!(
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Priority**: {priority}\n\
- **Tags**: test\n- **Due**: {due}\n- **Owner**: alice\n\
- **Status**: backlog\n"
);
fs::write(
worklane_dir
.join("backlog")
.join(format!("{uuid}_{}.md", slug(title))),
body,
)
.unwrap();
}
fn positions(stdout: &str, titles: [&str; 3]) -> Vec<usize> {
titles
.iter()
@@ -828,6 +856,57 @@ fn ls_orders_done_by_the_newest_entry_stamp() {
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
/// The backlog has no entry stamp, so the due date is its clock and the soonest deadline
/// heads the column. The p1 here is due last and is listed last, which is exactly what
/// priority alone got wrong.
#[test]
fn ls_orders_the_backlog_by_the_soonest_due_date() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("dddd000{n}-0000-0000-0000-000000000001");
create_due_ticket(&worklane, "Soonest", &at(1), "5", "2026-09-01");
create_due_ticket(&worklane, "Latest", &at(2), "1", "2026-09-03");
create_due_ticket(&worklane, "Between", &at(3), "3", "2026-09-02");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "backlog"]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Soonest", "Between", "Latest"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
// The overview lists the same column, so it has to agree with the narrowed listing
// rather than falling back to priority for the same tickets.
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).arg("ls");
let overview = get_stdout(&mut cmd);
let seen = positions(&overview, ["Soonest", "Between", "Latest"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{overview}");
}
/// A due nobody promised must not outrank one somebody did. The undated ticket here is
/// the most urgent of the three and still trails both, and among the dated ones the
/// equal due falls through to priority.
#[test]
fn ls_sinks_an_undated_backlog_ticket_below_the_dated_ones() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let at = |n: u8| format!("eeee000{n}-0000-0000-0000-000000000001");
create_due_ticket(&worklane, "Undated", &at(1), "1", "_Not set_");
create_due_ticket(&worklane, "Urgent", &at(2), "3", "2026-09-01");
create_due_ticket(&worklane, "Relaxed", &at(3), "5", "2026-09-01");
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
cmd.current_dir(temp.path()).args(["ls", "backlog"]);
let stdout = get_stdout(&mut cmd);
let seen = positions(&stdout, ["Urgent", "Relaxed", "Undated"]);
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
}
/// A missing stamp is unknown, not ancient, so it sinks below every stamped ticket
/// rather than claiming the head of the queue. Every ticket on a board older than the
/// stamps is one of these.
+134
View File
@@ -676,6 +676,140 @@ fn append_requires_at_least_one_section() {
assert_eq!(run(&temp, &["append", UUID]).status.code(), Some(2));
}
/// The reason the flag exists: `set --tags` writes the whole field, so adding one tag to
/// a ticket that already carries some meant knowing and retyping every one of them.
#[test]
fn append_adds_a_tag_and_keeps_the_ones_already_there() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &["append", UUID, "--tags", "beta"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
let content = ticket(&worklane);
assert!(content.contains("- **Tags**: alpha, beta"), "{content}");
// The sections and the other fields are as untouched as they are by any other append
assert!(content.contains("- [x] Crit one\n- [ ] Crit two\n"), "{content}");
assert!(content.contains("- **Priority**: 3"), "{content}");
}
/// Idempotent on purpose: the caller of an append does not have to know what is there
/// already, so naming a tag the ticket carries is reported as no change and writes
/// nothing, the way an unchanged field is everywhere else.
#[test]
fn append_ignores_a_tag_the_ticket_already_carries() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
let out = run(&temp, &["append", UUID, "--tags", "alpha"]);
assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
assert!(
String::from_utf8_lossy(&out.stdout).contains("No changes to"),
"{:?}",
String::from_utf8_lossy(&out.stdout)
);
assert_eq!(ticket(&worklane), before);
// And the one already there is not added a second time beside a new one
run(&temp, &["append", UUID, "--tags", "alpha", "--tags", "beta"]);
assert!(
ticket(&worklane).contains("- **Tags**: alpha, beta"),
"{}",
ticket(&worklane)
);
}
/// Two spellings for the same call, because the stored field is comma separated too and
/// `set --tags` takes that form on this very field: refusing it on the counterpart would
/// be a trap. New tags land in the order they were given, after the ones already there.
#[test]
fn append_takes_several_tags_by_repeated_flag_or_by_comma() {
for args in [
vec!["append", UUID, "--tags", "bug", "--tags", "tui"],
vec!["append", UUID, "--tags", "bug, tui"],
vec!["append", UUID, "-g", "bug,tui"],
] {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let out = run(&temp, &args);
assert!(
out.status.success(),
"{args:?}: {:?}",
String::from_utf8_lossy(&out.stderr)
);
assert!(ticket(&worklane).contains("- **Tags**: alpha, bug, tui"), "{args:?}");
}
}
/// A value that names no tag is refused rather than written, the way an all-blank section
/// value is: `--tags ","` adds nothing, and writing the field back unchanged would report
/// an append that never happened. Emptying the field is `set --clear tags`.
#[test]
fn append_refuses_a_tags_value_that_names_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane);
let before = ticket(&worklane);
// Empty at the parser, before the ticket is even resolved
let empty = run(&temp, &["append", UUID, "--tags", ""]);
assert_eq!(empty.status.code(), Some(2));
assert!(
String::from_utf8_lossy(&empty.stderr).contains("value cannot be empty"),
"{:?}",
String::from_utf8_lossy(&empty.stderr)
);
// The message must not name a `--clear` this command does not have
assert!(
!String::from_utf8_lossy(&empty.stderr).contains("use --clear"),
"{:?}",
String::from_utf8_lossy(&empty.stderr)
);
// Separators only, which the parser cannot see is empty
let blank = run(&temp, &["append", UUID, "--tags", ", ,"]);
assert_eq!(blank.status.code(), Some(1));
assert!(
String::from_utf8_lossy(&blank.stderr).contains("Nothing to append to the tags"),
"{:?}",
String::from_utf8_lossy(&blank.stderr)
);
assert_eq!(ticket(&worklane), before);
}
/// A ticket with no tags starts the list rather than appending to the sentinel.
#[test]
fn append_writes_the_first_tag_over_the_unset_sentinel() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
let mut add = Command::cargo_bin(BIN_NAME).unwrap();
add.current_dir(temp.path())
.args(["add", "--title", "Untagged"])
.assert()
.success();
let uuid = fs::read_dir(worklane.join("backlog"))
.unwrap()
.filter_map(|e| e.ok())
.map(|e| e.file_name().into_string().unwrap())
.next()
.map(|name| name.split('_').next().unwrap().to_string())
.unwrap();
run(&temp, &["append", &uuid, "--tags", "bug"]);
let content = ticket(&worklane);
assert!(content.contains("- **Tags**: bug"), "{content}");
assert!(!content.contains("_None_"), "{content}");
}
/// Owner belongs to chown and status to mv, so neither command offers them.
#[test]
fn neither_command_can_write_owner_or_status() {
+11 -1
View File
@@ -397,7 +397,17 @@ fn the_file_is_created_on_a_board_that_predates_it() {
#[test]
fn init_writes_the_vocabulary_beside_the_status_directories() {
let temp = TempDir::new().unwrap();
let out = run(&temp, &["init"]);
// Isolated HOME and XDG so `init` cannot decide on a real machine's boards config:
// the board has to be local no matter whose machine runs the suite.
let mut out = Command::cargo_bin(BIN_NAME).unwrap();
let out = out
.current_dir(temp.path())
.env("HOME", temp.path())
.env("XDG_CONFIG_HOME", temp.path().join("config"))
.env("XDG_DATA_HOME", temp.path().join("data"))
.arg("init")
.output()
.unwrap();
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let file = vocabulary(&temp);
+45 -3
View File
@@ -275,6 +275,36 @@ fn clearing_the_tags_writes_a_tags_entry() {
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
}
/// Tags are logged wherever they change, so the command that adds to them logs the same
/// entry the one that replaces them does. The values come off the field rather than off
/// the flag, so the entry records where the field went and not what the call added: an
/// append of `beta` onto `alpha` reads as the pair, not as `beta`.
#[test]
fn appending_a_tag_writes_a_tags_entry() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["append", UUID, "--tags", "beta"]);
let entry = only_entry(&worklane, "tags");
assert!(entry.starts_with("**Tags**\nalpha → alpha, beta\n"), "{entry:?}");
}
/// The sections are not logged, and appending to one is not a tag change: an append that
/// touches no tag writes nothing, so the log does not fill with the edits it deliberately
/// leaves out.
#[test]
fn appending_to_a_section_writes_nothing() {
let temp = TempDir::new().unwrap();
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
run(&temp, &["append", UUID, "--acceptance", "One more criterion"]);
assert_eq!(entries(&worklane), vec![]);
}
/// The entry names the campaign the way a reader knows it, the codename, not the uuid
/// the field actually holds. A ticket never assigned starts from the sentinel an unset
/// field reads as everywhere else.
@@ -433,6 +463,7 @@ fn a_no_op_edit_writes_nothing() {
vec!["mv", UUID, "--status", "backlog"],
vec!["chown", "alice", UUID],
vec!["set", UUID, "--tags", "alpha"],
vec!["append", UUID, "--tags", "alpha"],
] {
let out = run(&temp, &args);
assert!(
@@ -577,10 +608,11 @@ fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
run(&temp, &["append", UUID, "--tags", "gamma", "--actor", "opencode"]);
run(&temp, &["assign", "v1", UUID, "--actor", "opencode"]);
let found = entries(&worklane);
assert_eq!(found.len(), 5, "{found:?}");
assert_eq!(found.len(), 6, "{found:?}");
for (name, content) in found {
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
}
@@ -609,10 +641,11 @@ fn actor_from_git_names_the_git_user_on_every_command_that_writes_one() {
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, &["append", UUID, "--tags", "gamma", "--actor-from-git"]);
run_for_the_human(&temp, &["assign", "v1", UUID, "--actor-from-git"]);
let found = entries(&worklane);
assert_eq!(found.len(), 5, "{found:?}");
assert_eq!(found.len(), 6, "{found:?}");
for (name, content) in found {
assert!(content.contains("**Author**: Ansho Rei"), "{name}: {content:?}");
}
@@ -627,7 +660,7 @@ fn actor_and_actor_from_git_are_refused_together() {
let worklane = setup_worklane(&temp);
create_ticket(&worklane, "backlog");
let calls: [&[&str]; 5] = [
let calls: [&[&str]; 6] = [
&[
"comment",
UUID,
@@ -662,6 +695,15 @@ fn actor_and_actor_from_git_are_refused_together() {
"opencode",
"--actor-from-git",
],
&[
"append",
UUID,
"--tags",
"beta",
"--actor",
"opencode",
"--actor-from-git",
],
&[
"assign",
"v1",