Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
239d951b8c | ||
|
|
f515d69930 | ||
|
|
b1dbf3ed75 | ||
|
|
154ffbdeb3 | ||
|
|
50e67483d8 | ||
|
|
11145b228e | ||
|
|
2ddd0addf6 | ||
|
|
cbc20848f6 | ||
|
|
eae411ab50 |
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
---
|
||||
|
||||
# Feature Planner Agent
|
||||
|
||||
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
"testing-skill": "allow"
|
||||
---
|
||||
|
||||
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
id: worklane_kanban
|
||||
name: worklane_kanban
|
||||
version: 1.0.0
|
||||
description: >
|
||||
Creates Kanban-style tickets in Worklane using the `worklane add` CLI command.
|
||||
Supports listing tickets with `worklane ls`. Both commands support title, description,
|
||||
acceptance criteria, implementation plan, tags, due date, owner assignment, and status filtering.
|
||||
rendering:
|
||||
strategy: cli_args
|
||||
join_arrays_with: ","
|
||||
omit_empty: true
|
||||
---
|
||||
|
||||
# Worklane Kanban Skill
|
||||
|
||||
Use this skill when creating, listing, or managing Kanban-style tickets via the `worklane` CLI.
|
||||
|
||||
When asked to "create a ticket", use the `worklane add` command.
|
||||
When using backticks in the command arguments, escape them so the terminal doesn't execute them.
|
||||
|
||||
When asked to "implement", "work on" or "read" a ticket, use the `worklane show` command.
|
||||
|
||||
## Commands
|
||||
|
||||
### `worklane add`
|
||||
|
||||
Add a new ticket to the backlog.
|
||||
|
||||
**Required:**
|
||||
- `--title` (or `-t`): Ticket title
|
||||
|
||||
**Optional:**
|
||||
- `--description` (or `-d`): Ticket description
|
||||
- `--acceptance` (or `-a`): Acceptance criteria (repeat flag for each criterium)
|
||||
- `--plan` (or `-p`): Implementation plan steps (repeat flag for each step)
|
||||
- `--tags` (or `-g`): Tags (comma-separated)
|
||||
- `--due`: Due date in YYYY-MM-DD format. No short form
|
||||
- `--owner` (or `-o`): Owner name
|
||||
- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted. No short form
|
||||
|
||||
Tags are `-g`, not `-t`: `-t` is the title, and passing it twice is an error. Each
|
||||
plan step needs its own `-p`, since a bare value after one is not a second step.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement login" -d "Add user login page" -g login,auth -p "Design UI" -p "Build backend" -p "Write tests" --due 2026-06-01 --owner "ilya"
|
||||
```
|
||||
|
||||
When there's multiple acceptance criteria, add each using a separate `--acceptance` or `-a` flag.
|
||||
When there's mulitple steps to the implementation plan, add each using a separate `--plan` or `-p` flag.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement logic" -a "Acceptance criterium 1" -a "Acceptance criterium 2" -p "Step 1" -p "Step 2"
|
||||
```
|
||||
|
||||
### `worklane ls`
|
||||
|
||||
List tickets, optionally filtered by status.
|
||||
|
||||
**Valid statuses:** `backlog`, `committed`, `reviewing`, `done`
|
||||
|
||||
```
|
||||
worklane ls # List all tickets
|
||||
worklane ls backlog # List tickets in backlog
|
||||
worklane ls done # List completed tickets
|
||||
worklane ls --priority 1 # Only the most urgent, any status
|
||||
worklane ls backlog --priority 2 # Composes with the status filter
|
||||
```
|
||||
|
||||
Tickets are listed priority first, then by title. Tickets with no priority sort last.
|
||||
|
||||
### `worklane show`
|
||||
|
||||
Show the full details of a single ticket by UUID or title.
|
||||
|
||||
```
|
||||
worklane show "ticket title or uuid"
|
||||
```
|
||||
|
||||
### `worklane mv`
|
||||
|
||||
Move a ticket between statuses.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<id>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Required options:**
|
||||
- `--status <target>`: Target status (`backlog`, `committed`, `reviewing`, `done`)
|
||||
|
||||
**Options:**
|
||||
- `-f`: Force move (allows skipping stages and backward moves)
|
||||
|
||||
**Default behavior:** Only allows forward moves, one stage at a time (`backlog` -> `committed` -> `reviewing` -> `done`).
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane mv ticket-id --status committed # Move forward one stage
|
||||
worklane mv ticket-title --status reviewing -f # Force skip stages
|
||||
worklane mv a1b2c3d4 --status committed # Move by UUID prefix
|
||||
worklane mv "My Ticket" --status done -f # Move by title with force
|
||||
```
|
||||
|
||||
### `worklane set`
|
||||
|
||||
Replace fields on an existing ticket. Only the fields given are touched; ticked
|
||||
criteria and handwritten sections are left alone. At least one field is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--title`, `--description` (or `-d`), `--acceptance` (or `-a`), `--plan`
|
||||
(or `-p`), `--tags` (or `-g`), `--due`, `--priority`
|
||||
|
||||
Owner is not settable here, and neither is status: `chown` owns owner and `mv` owns
|
||||
status. Changing the title renames the file, keeping the UUID.
|
||||
|
||||
```bash
|
||||
worklane set a1b2c3d4 --priority 1
|
||||
worklane set a1b2c3d4 --title "A clearer title" --due 2026-12-31
|
||||
worklane set a1b2c3d4 -a "First criterium" -a "Second criterium"
|
||||
```
|
||||
|
||||
### `worklane append`
|
||||
|
||||
Add to a section without replacing what is there. The description gains a new
|
||||
paragraph; criteria and steps go on the end of their lists, steps numbered on from
|
||||
the last. At least one section is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--description` (or `-d`), `--acceptance` (or `-a`), `--plan` (or `-p`)
|
||||
|
||||
```bash
|
||||
worklane append a1b2c3d4 -d "A paragraph amending the description."
|
||||
worklane append a1b2c3d4 -a "One more criterium"
|
||||
worklane append a1b2c3d4 -p "A later step"
|
||||
```
|
||||
|
||||
### `worklane chown`
|
||||
|
||||
Set the owner of a ticket. The only command that writes the Owner field: `set` does
|
||||
not offer it.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<user>`: The new owner. Free text, checked against nothing
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
The user comes first and the ticket second, after Unix `chown`. That is the one
|
||||
command here that does not start with the ticket, so mind the order: swap the two and
|
||||
the call fails, because the username has to resolve as a ticket. An owner set to the
|
||||
value it already holds is reported unchanged and nothing is written.
|
||||
|
||||
```bash
|
||||
worklane chown alice a1b2c3d4
|
||||
worklane chown "Ansho Rei" "A clearer title"
|
||||
```
|
||||
|
||||
### `worklane check` and `worklane uncheck`
|
||||
|
||||
Tick or untick a single acceptance criterion. Every other criterion keeps its state,
|
||||
and handwritten lines in the section are left alone.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `[criterion]`: The number as shown by `worklane show`, or a substring of its text
|
||||
|
||||
Omit the criterion and the numbered criteria are listed and the number asked for. With
|
||||
no terminal, as when driving the CLI from a tool, the same list comes back as an error
|
||||
instead, so re-run with the number. A substring matching more than one criterion is an
|
||||
error listing the matches with their real numbers.
|
||||
|
||||
```bash
|
||||
worklane check a1b2c3d4 2
|
||||
worklane check a1b2c3d4 "renames the file"
|
||||
worklane uncheck a1b2c3d4 2
|
||||
```
|
||||
|
||||
### `worklane comment`
|
||||
|
||||
Add a comment to a ticket.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `<body>`: Comment text
|
||||
|
||||
Comments are stored as timestamped markdown files in `.worklane/comments/<ticket-uuid>/` and include the git author and timestamp.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane comment ticket-id "Reviewed, looks good"
|
||||
worklane comment "My Ticket" "Needs changes to the UI"
|
||||
worklane comment a1b2c3d4 "LGTM, approved"
|
||||
```
|
||||
|
||||
## Working a ticket
|
||||
|
||||
Move the ticket as you work it, not afterwards. The board should say what is happening
|
||||
now, not only what already landed.
|
||||
|
||||
1. `worklane show <id>` to read it
|
||||
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
|
||||
the ticket as being worked on, so it belongs at the start
|
||||
3. Do the work. `worklane check <id> <n>` as each criterion is met
|
||||
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
|
||||
acceptance criterion, something the ticket got wrong
|
||||
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
|
||||
|
||||
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
|
||||
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
|
||||
makes moving it up front the same two commands in a more useful order.
|
||||
|
||||
## Commands
|
||||
|
||||
- `worklane add` creates tickets with all relevant details
|
||||
- `worklane ls [status]` views tickets by status
|
||||
- `worklane show <id>` views full ticket details
|
||||
- `worklane mv <id> --status <target>` moves tickets through the workflow
|
||||
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
|
||||
- `worklane check <ticket> <n>` ticks a criterion as it is met
|
||||
- `worklane comment <ticket> <body>` adds notes to tickets
|
||||
@@ -13,6 +13,7 @@
|
||||
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
|
||||
- `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI
|
||||
- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
|
||||
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
|
||||
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
@@ -22,7 +23,8 @@
|
||||
- Filenames: `<uuid_v4>_<slug>.md`
|
||||
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
|
||||
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
|
||||
- Format: `**Field Name**: value`
|
||||
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
|
||||
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
|
||||
@@ -217,11 +219,15 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `detail_title` cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
|
||||
- The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason
|
||||
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
|
||||
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, criteria count bottom right. The two numbers are in corners because that is where the eye goes for one, and both were invisible at the end of a line of prose
|
||||
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
|
||||
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
|
||||
- **A card's height therefore depends on the column's width**, so `card_lines` and `card_height` both take it. `column_areas` is shared between the draw and `follow_selection` for the same reason: `Ratio` hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
|
||||
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
|
||||
- **`corner_line`'s right side is a group, single-spaced, and it gives up its items from the front.** The item nearest the edge is what the corner is *about*; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an `Option`. The spacing between the items lives in `corner_line` with the gap arithmetic rather than in a caller, for the reason `column_areas` is shared: geometry reproduced by hand drifts from the draw. `due_span` returns a `Span` and not an `Option<Span>` now, since the `Option` only ever existed to satisfy the old signature and the function cannot fail
|
||||
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
|
||||
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The comments live outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_comments` applies, and no body is read, because a count needs none of them. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the comments of another. `comments_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
|
||||
- **The count is cyan and the mark is `COMMENT_MARK`, U+275E, a Dingbat.** It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where `spans_width` counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
|
||||
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the comments directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
|
||||
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
|
||||
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
|
||||
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
|
||||
@@ -235,6 +241,20 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`picker: Option<Picker>` is the whole mode**, the shape `search` and `detail` use, and `Board::picker_key` runs beside `search_key` ahead of the action arms for the same reason: an open list owns the keyboard, so `d` must not toggle done and `q` must not quit while a campaign is being chosen. `ctrl-c` is the one key it declines and every other control combination is swallowed, or `ctrl-d` would reach the arm bound to `d`
|
||||
- **The picker's rows are `Tab::campaigns`, not a copy taken when it opened**, so a campaign filed elsewhere appears in an open picker on the next tick. It opens on the campaign already selected, so `c` on a filtered board says where you are as well as offering somewhere to go, and a board with no campaigns gets a `Notice` rather than an empty box that has to be dismissed to learn it was empty
|
||||
- **A picker row draws a real codename only.** The row opens with the short id, so the card's `~<id>` fallback would print it twice and say nothing the second time
|
||||
- **The picker draws two sections, open campaigns above completed, and truncates the completed tail.** One flat list by title put the finished campaigns among the open ones forever, and the tail only grows, so on a board that has run for a while the campaigns worth picking were pushed towards the bottom of the box and eventually off it. Open keeps the index's order, which is by title; completed is by `Created At` newest first, because what a reader recognises about a finished campaign is that it was finished recently. `COMPLETED_SHOWN` of them survive, behind a grey line naming how many older ones are being kept back — rows that are simply gone read as a board that never held them. An unstamped campaign sinks below every stamped one, the rule `by_status_order` holds for a column
|
||||
- **`picker_list` is the one place that decides what a picker row is**, and `Picker::row` counts *drawn* rows. The sections reorder the campaigns and add rows of their own, so `Tab::campaigns` and the drawn list agree about no number past the first heading, and a row number that meant one thing to the draw and another to a keypress is how a highlight comes to name a campaign nobody chose. The list is derived on every draw and every keypress and never held, which is what keeps a campaign filed elsewhere reaching an open picker on the next tick
|
||||
- **A heading is drawn only over rows that exist**, the bargain an untagged card's label row already makes, and it says which kind its rows are for as long as they are there — which is what a query filtering down to completed campaigns alone has to go on saying
|
||||
- **`open` and `completed`, not `open` and `done`.** The split is taken from `Standing::state`, so the section a campaign lands in and the state the frame draws cannot come to disagree about what finished means, but the word is the section's own: a campaign sits in no status directory, so it is not *in* done the way a ticket under that heading is. A campaign with no members is neither, per that method, and lists as open — completed means every member is done, and it holds none to be done
|
||||
- **Headings and the truncation line take no number: the highlight moves over campaigns only.** `stepped_picker_row` walks past the chrome rather than stopping on it, since a highlight resting on a heading gives `enter` nothing to do, and a step that runs out of campaigns is no move at all, the way a card at the end of a column clamps rather than cycling
|
||||
- **`/` in the picker is the key it already is on the board**, and `picker_key` can take it because printable keys used to fall through `_ => {}`. Typing filters case insensitively against the short id, the codename and the title — the three things the row draws and the three a campaign is chosen by. Not the summary: a query that matched prose would answer `disk` with every campaign whose description mentions one. **An empty query matches everything**, the opposite of `first_match`'s answer and right for the opposite reason: a jump with nothing typed has nowhere to go, while a filter with nothing typed is not filtering, and pressing `/` must not empty the list
|
||||
- **A query turns the truncation off**, which is the point of having one: the campaign a reader is searching for is exactly the one the truncation hid
|
||||
- **The query is a layer, and `esc` takes it off before it takes the picker off**, the order `dismiss` closes the board's own layers in. So the list is whole again after that press, not still filtered with nothing on screen saying why. Movement and `enter` stay live under an open query, because a filtered list nothing can move in is a list nothing can be chosen from; every *printable* key goes into the buffer, so `q` types and so does `j`
|
||||
- **The highlight follows its campaign, not its row number.** `place_picker` takes a uuid, the answer `Tab::campaign` already gives for the filter: typing, clearing the query and a tick that finishes a campaign all reshape the list, and a number kept across that names whichever campaign now sits at it. One the list no longer holds drops the highlight to the first row that does, which is where an incremental filter puts it. `reload` reads the highlighted uuid before the lists are rebuilt and puts it back after
|
||||
- **A miss is a row in the box, `no match` in brightred**, where the search prompt puts its own, and `enter` on it leaves the picker and the query exactly as they are so the query can be corrected in place. An empty box says nothing about why it is empty
|
||||
- **The picker's footer becomes its query**, the trade `draw_search` makes: with every printable key going into a buffer, a list of keys describes nothing that works. `/ search` is named only on the closed query, and the open one names what `esc` does to *it* rather than what it does to the picker
|
||||
- **The title says both counts while a query is open**, `campaigns (2 of 6)`. The bare total is what the box is, but over a list a query has cut down it is a lie about what is on screen
|
||||
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
|
||||
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
|
||||
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
|
||||
@@ -302,6 +322,13 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
|
||||
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
|
||||
|
||||
### Finding the Board
|
||||
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
|
||||
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
|
||||
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
|
||||
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
|
||||
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
|
||||
|
||||
### Monitoring Several Boards
|
||||
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
|
||||
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
|
||||
@@ -309,7 +336,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 `show_done` 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. That comparator is exported for this and is the one `collect_ticket_items` uses, so the two orders cannot drift
|
||||
- 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
|
||||
- `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
|
||||
@@ -318,13 +345,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
### Shipping the Agent Assets
|
||||
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
|
||||
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
|
||||
- **One install path serves both agents:** `~/.claude/skills/worklane/SKILL.md`. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own `~/.config/opencode/skill/`. Verified against opencode 1.15.10, whose built-in `customize-opencode` skill documents the table and whose `opencode debug skill` lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
|
||||
- `Asset` carries the content, the path under its root and the word used in messages, so `install-tool` adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is `install.rs` and not `skill.rs`
|
||||
- `install()` takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects `HOME` for the same reason
|
||||
- **A modified copy is refused, not overwritten.** Someone may have edited it on purpose, and the message names `--print` so it can be diffed and `--force` so it can be replaced. A read error is not treated as absent either: the write reports the real reason
|
||||
- Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every `worklane <x>` the skill shows has to be a real subcommand, and every subcommand outside `NOT_FOR_AGENTS` has to appear in the skill. The last one catches a new command that nothing tells an agent about
|
||||
- `install-skill` looks for no board. The skill is what teaches an agent worklane, so needing a `.worklane` to install it would put it out of reach exactly when it is wanted
|
||||
- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question
|
||||
- The **agent files** under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question. The tool file is the exception and no longer lives there: it was `.opencode/tools/worklane.ts`, which meant it existed only inside a checkout, and it is now `assets/TOOL.ts` and shipped like every other asset
|
||||
- **`install-skill` writes every shipped document, and the name narrows it.** One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog
|
||||
- **`--print` requires the name.** It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the `comment --` body makes
|
||||
- The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what
|
||||
@@ -333,6 +361,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding)
|
||||
- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
|
||||
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
|
||||
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
|
||||
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
|
||||
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
|
||||
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
|
||||
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
|
||||
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
|
||||
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
|
||||
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
|
||||
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
|
||||
|
||||
### Color and Output
|
||||
|
||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.21.1"
|
||||
version = "0.26.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.21.1"
|
||||
version = "0.26.0"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -5,7 +5,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
## Commands
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator 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; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. 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` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator 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 and says how far it has got, and `q` on its border gives the whole board back. 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 directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
|
||||
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
|
||||
@@ -26,6 +26,7 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
|
||||
| `worklane completions <shell>` | Prints a completion script for `fish`, `bash`, `zsh`, `elvish` or `powershell`. See below |
|
||||
| `worklane install-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Three ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
|
||||
|
||||
## Completions
|
||||
|
||||
|
||||
+16
-9
@@ -201,26 +201,33 @@ pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result
|
||||
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
|
||||
let mut grouped = Vec::new();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
// Over `Status::ALL` rather than the names, so each group can be put in its own
|
||||
// column's order: a campaign's committed list answers what has waited longest for
|
||||
// the same reason the board's column does.
|
||||
for status in Status::ALL {
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
let items = match status_path.exists() {
|
||||
true => collect_ticket_items(&status_path)?,
|
||||
false => Vec::new(),
|
||||
};
|
||||
|
||||
grouped.push((
|
||||
status,
|
||||
items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect(),
|
||||
));
|
||||
let mut members: Vec<TicketItem> = items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect();
|
||||
members.sort_by(|a, b| by_status_order(status, a, b));
|
||||
|
||||
grouped.push((status.as_str(), members));
|
||||
}
|
||||
|
||||
Ok(grouped)
|
||||
}
|
||||
|
||||
/// How far a campaign has got: members done against members held.
|
||||
///
|
||||
/// `Copy` because the board carries one on every `CampaignRow`, settled at reload: two
|
||||
/// counters are cheaper to copy than to reach back through a reference for.
|
||||
#[derive(Clone, Copy, Debug, Default)]
|
||||
pub struct Standing {
|
||||
pub done: usize,
|
||||
pub total: usize,
|
||||
|
||||
+145
-3
@@ -130,6 +130,56 @@ fn codename(raw: &str) -> Result<String, String> {
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
/// Reject a tag value that `ls --tag` could never match.
|
||||
///
|
||||
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
|
||||
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
|
||||
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
|
||||
/// `tags.md`, and a heading is one line.
|
||||
///
|
||||
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
|
||||
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
|
||||
/// vocabulary. Refusing here would refuse a value that both of those accept.
|
||||
///
|
||||
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
|
||||
fn tag_value(raw: &str) -> Result<String, String> {
|
||||
let value = raw.trim();
|
||||
|
||||
if value.is_empty() {
|
||||
return Err("tag cannot be empty".to_string());
|
||||
}
|
||||
|
||||
if value.contains(',') {
|
||||
return Err(
|
||||
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
|
||||
);
|
||||
}
|
||||
|
||||
if value.contains(['\n', '\r']) {
|
||||
return Err("tag must be a single line".to_string());
|
||||
}
|
||||
|
||||
Ok(value.to_string())
|
||||
}
|
||||
|
||||
/// Reject an annotation line that would be read back as a tag of its own.
|
||||
///
|
||||
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
|
||||
/// starting with the section marker would split the annotation and declare whatever
|
||||
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
|
||||
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
|
||||
/// a different line.
|
||||
fn annotation_line(raw: &str) -> Result<String, String> {
|
||||
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
|
||||
true => Err(format!(
|
||||
"an annotation line cannot start with '{}', which is how the vocabulary file \
|
||||
starts a tag",
|
||||
crate::tag::SECTION
|
||||
)),
|
||||
false => Ok(raw.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -244,15 +294,18 @@ pub enum Command {
|
||||
ticket: String,
|
||||
},
|
||||
|
||||
/// List the tags the board carries, and how many tickets carry each
|
||||
/// The tag vocabulary: what the board carries, and what each tag means
|
||||
///
|
||||
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
|
||||
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
|
||||
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
|
||||
/// a filter that means something else.
|
||||
///
|
||||
/// The output is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags,
|
||||
/// The listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags {
|
||||
#[command(subcommand)]
|
||||
command: Option<TagCommand>,
|
||||
},
|
||||
|
||||
/// Print a shell completion script
|
||||
///
|
||||
@@ -281,6 +334,23 @@ pub enum Command {
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
|
||||
/// Install the opencode tool definitions that wrap the worklane CLI
|
||||
///
|
||||
/// One artifact, so no name to pass where `install-skill` takes an optional one:
|
||||
/// `--print` here can only mean the one file. opencode alone, and globally, so the
|
||||
/// tools are there in every project rather than in a checkout that happens to carry
|
||||
/// them. Claude Code has no directory it scans for a tool definition; reaching it
|
||||
/// would mean an MCP server, which is not this file.
|
||||
InstallTool {
|
||||
/// Overwrite an existing copy that has been modified
|
||||
#[arg(long)]
|
||||
force: bool,
|
||||
|
||||
/// Write it to stdout instead of installing it
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
}
|
||||
|
||||
/// What a campaign can be asked for.
|
||||
@@ -412,6 +482,78 @@ pub struct CampaignAddArgs {
|
||||
pub owner: Option<String>,
|
||||
}
|
||||
|
||||
/// What the tag vocabulary can be asked for.
|
||||
///
|
||||
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
|
||||
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
|
||||
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
|
||||
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
|
||||
/// ls` is the same thing spelled the way `campaign ls` is.
|
||||
///
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum TagCommand {
|
||||
/// Declare a tag, and what it means
|
||||
Add(TagAddArgs),
|
||||
|
||||
/// Replace what a declared tag means
|
||||
Set(TagSetArgs),
|
||||
|
||||
/// List the tags the board carries, and how many tickets carry each
|
||||
Ls,
|
||||
}
|
||||
|
||||
/// What declaring a tag takes: the tag, and what it is for.
|
||||
///
|
||||
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
|
||||
/// not an object with a history, it is a word the board agrees on, and `git log` over
|
||||
/// `tags.md` answers who wrote which line better than a field would.
|
||||
#[derive(clap::Args)]
|
||||
pub struct TagAddArgs {
|
||||
/// The tag to declare, spelled the way `ls --tag` matches it
|
||||
#[arg(value_parser = tag_value)]
|
||||
pub tag: String,
|
||||
|
||||
/// What the tag means and when it is appropriate. Use multiple flags for multiline
|
||||
/// annotations
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
|
||||
pub annotation: Vec<String>,
|
||||
}
|
||||
|
||||
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
|
||||
///
|
||||
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
|
||||
/// has one it is how the campaign is addressed, on every card and at every command line, so
|
||||
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
|
||||
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
|
||||
/// command's whole purpose.
|
||||
///
|
||||
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
|
||||
/// ticket carrying it. That is a migration, not a flag on `set`.
|
||||
///
|
||||
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
|
||||
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
|
||||
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
|
||||
///
|
||||
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
|
||||
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
|
||||
#[derive(clap::Args)]
|
||||
pub struct TagSetArgs {
|
||||
/// The tag to change, spelled the way it is declared
|
||||
#[arg(value_parser = tag_value)]
|
||||
pub tag: String,
|
||||
|
||||
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
|
||||
/// multiple flags for multiline annotations
|
||||
#[arg(
|
||||
short,
|
||||
long,
|
||||
required = true,
|
||||
allow_hyphen_values = PROSE,
|
||||
value_parser = annotation_line
|
||||
)]
|
||||
pub annotation: Vec<String>,
|
||||
}
|
||||
|
||||
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
|
||||
/// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option<String>`
|
||||
/// values that a caller can swap silently, so the mode that joined them came as a
|
||||
|
||||
+50
-7
@@ -66,6 +66,15 @@ pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
/// one where `ls --ids` answers the tickets.
|
||||
pub const TAG_FLAGS: [&str; 1] = ["tag"];
|
||||
|
||||
/// Nested commands whose first argument is a tag the board already has.
|
||||
///
|
||||
/// `tags set` changes what a declared tag means, so the values it takes are exactly the
|
||||
/// ones `worklane tags` prints. `tags add` is deliberately absent: the tag it takes is one
|
||||
/// the board does not have yet, so offering the ones it does would offer exactly the values
|
||||
/// it refuses. Which of the two a new tag positional belongs to is what
|
||||
/// `no_tag_taking_option_is_missing` makes somebody decide.
|
||||
pub const TAG_NESTED_COMMANDS: [(&str, &str); 1] = [("tags", "set")];
|
||||
|
||||
pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> {
|
||||
let mut command = crate::command::Cli::command();
|
||||
clap_complete::generate(shell, &mut command, "worklane", out);
|
||||
@@ -92,6 +101,11 @@ fn fish_dynamic() -> String {
|
||||
.join("; or ");
|
||||
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
|
||||
let tag_flags = flag_list(&TAG_FLAGS);
|
||||
let tag_nested = TAG_NESTED_COMMANDS
|
||||
.iter()
|
||||
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join("; or ");
|
||||
let statuses = possible_values(Status::value_variants());
|
||||
let shells = possible_values(Shell::value_variants());
|
||||
let skills = SKILLS
|
||||
@@ -182,6 +196,11 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
|
||||
# worth reading: it says which spelling the board actually uses.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
|
||||
|
||||
# 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
|
||||
# here are the values it refuses.
|
||||
complete -c worklane -n '{tag_nested}' -a '(worklane tags)'
|
||||
|
||||
# `chown --clear` names the ticket in the flag too, since with no user to give there is
|
||||
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
|
||||
# has a `--clear` of its own that takes a field name, and clap already offers those.
|
||||
@@ -351,6 +370,18 @@ mod tests {
|
||||
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
|
||||
}
|
||||
|
||||
/// Commands whose tag positional names a tag that does not exist yet.
|
||||
///
|
||||
/// `tags add` declares a word the board has never carried, so completing it from
|
||||
/// `worklane tags` would offer exactly the values the command refuses. Recorded rather
|
||||
/// than skipped, so the *next* tag positional has to say which it is: `tags set` takes
|
||||
/// a tag that is already declared and wants a rule in the fish block, and the test
|
||||
/// below fails until it gets one or lands here.
|
||||
///
|
||||
/// In the test module because nothing outside it reads the list; the rule it encodes is
|
||||
/// about what the fish block is missing, which is a test's question.
|
||||
const TAG_NEW_COMMANDS: [(&str, &str); 1] = [("tags", "add")];
|
||||
|
||||
/// 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.
|
||||
@@ -363,19 +394,31 @@ mod tests {
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
let long = arg.get_long().unwrap_or_else(|| {
|
||||
panic!(
|
||||
"`worklane {name}` takes a tag as a positional, \
|
||||
which the fish block has no rule for"
|
||||
)
|
||||
});
|
||||
|
||||
let Some(long) = arg.get_long() else {
|
||||
let known = match path.as_slice() {
|
||||
[parent, child] => {
|
||||
let pair = (parent.as_str(), child.as_str());
|
||||
TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair)
|
||||
}
|
||||
_ => false,
|
||||
};
|
||||
assert!(
|
||||
known,
|
||||
"`worklane {name}` takes a tag as a positional, so it belongs in \
|
||||
TAG_NESTED_COMMANDS if the tag already exists and TAG_NEW_COMMANDS if it \
|
||||
does not"
|
||||
);
|
||||
continue;
|
||||
};
|
||||
|
||||
assert!(
|
||||
TAG_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 1, "expected ls --tag");
|
||||
assert_eq!(seen, 3, "expected ls --tag, tags add and tags set");
|
||||
}
|
||||
|
||||
/// **Every rule naming an option has to say which command it belongs to.** A bare
|
||||
|
||||
+207
-29
@@ -8,9 +8,10 @@ use std::path::Path;
|
||||
use crate::campaign::*;
|
||||
use crate::command::{
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
|
||||
RelateArgs, SetArgs,
|
||||
RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
|
||||
};
|
||||
use crate::install;
|
||||
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
|
||||
use crate::util::*;
|
||||
|
||||
pub fn cmd_init(start: &Path) -> Result<()> {
|
||||
@@ -33,6 +34,13 @@ pub fn cmd_init(start: &Path) -> Result<()> {
|
||||
// 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())?;
|
||||
|
||||
println!("Initialized worklane in: {}", worklane_dir.display());
|
||||
Ok(())
|
||||
}
|
||||
@@ -63,8 +71,10 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
}
|
||||
|
||||
if let Some(status) = args.status {
|
||||
let status = status.as_str();
|
||||
let status_path = worklane_dir.join(status);
|
||||
// The `Status` is kept alongside its name: the directory is joined from the
|
||||
// name, and the order the column prints in is keyed on the status itself.
|
||||
let name = status.as_str();
|
||||
let status_path = worklane_dir.join(name);
|
||||
if !status_path.exists() {
|
||||
// The status itself is clap's to reject now, so reaching here means the
|
||||
// board is missing a directory it should have rather than that the name was
|
||||
@@ -72,19 +82,20 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
// alone.
|
||||
return Err(anyhow!(
|
||||
"No '{}' directory in {}. Every board has all four; creating it is enough.",
|
||||
status,
|
||||
name,
|
||||
worklane_dir.display()
|
||||
));
|
||||
}
|
||||
|
||||
let items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
|
||||
let mut items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
|
||||
if items.is_empty() {
|
||||
println!("No tickets in '{}' status.", status);
|
||||
println!("No tickets in '{}' status.", name);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
println!("Tickets in '{}' status:\n", status);
|
||||
println!("Tickets in '{}' status:\n", name);
|
||||
display_ticket_items(&items);
|
||||
} else {
|
||||
// List all statuses with their ticket counts
|
||||
@@ -101,23 +112,27 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
println!(" [{}] {} {}", status.to_uppercase(), count, label);
|
||||
}
|
||||
|
||||
// Show all tickets except done grouped by status
|
||||
for status in &statuses {
|
||||
if *status == DONE {
|
||||
// Show all tickets except done grouped by status. Over `Status::ALL` rather
|
||||
// than the names, because each column is ordered by its own entry stamp and the
|
||||
// comparator is keyed on the status, not on the directory it was read from.
|
||||
for status in Status::ALL {
|
||||
if status.as_str() == DONE {
|
||||
continue;
|
||||
}
|
||||
let status_path = worklane_dir.join(status);
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
if !status_path.exists() || !fs::metadata(&status_path)?.is_dir() {
|
||||
continue;
|
||||
}
|
||||
let items = match collect_ticket_items(&status_path) {
|
||||
let mut items = match collect_ticket_items(&status_path) {
|
||||
Ok(items) => filtered(items, priority_filter, uuid, tag),
|
||||
Err(_) => continue,
|
||||
};
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
if items.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let status_header = color_text(&format!("[{}]", status.to_uppercase()), Color::Orange);
|
||||
let status_header =
|
||||
color_text(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange);
|
||||
println!("\n{}", status_header);
|
||||
display_ticket_items(&items);
|
||||
}
|
||||
@@ -150,16 +165,20 @@ fn list_ids(
|
||||
worklane_dir: &Path,
|
||||
) -> Result<()> {
|
||||
let statuses = match status {
|
||||
Some(status) => vec![status.as_str()],
|
||||
None => status_dirs(),
|
||||
Some(status) => vec![status],
|
||||
None => Status::ALL.to_vec(),
|
||||
};
|
||||
|
||||
for status in statuses {
|
||||
let status_path = worklane_dir.join(status);
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
if !status_path.exists() {
|
||||
continue;
|
||||
}
|
||||
for item in filtered(collect_ticket_items(&status_path)?, level, campaign, tag) {
|
||||
// The same order the listing prints, so a completion and the board agree on
|
||||
// which ticket is at the head of a column.
|
||||
let mut items = filtered(collect_ticket_items(&status_path)?, level, campaign, tag);
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
for item in items {
|
||||
println!("{}\t{}", item.id, item.title);
|
||||
}
|
||||
}
|
||||
@@ -434,7 +453,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
println!("\n{}", content_trim_colored(&content, &resolved));
|
||||
|
||||
if ticket_uuid != "_Not set_" {
|
||||
let comments_dir = worklane_dir.join("comments").join(&ticket_uuid);
|
||||
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
|
||||
let comments = read_comments(&comments_dir)?;
|
||||
let formatted = format_comments(&comments);
|
||||
println!("{}", formatted);
|
||||
@@ -451,6 +470,7 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
/// mid-sentence so there is no capital to case.
|
||||
const TICKET: &str = "ticket";
|
||||
const CAMPAIGN: &str = "campaign";
|
||||
const TAG: &str = "tag";
|
||||
|
||||
/// Write `content` over `path`, without ever leaving half a file behind.
|
||||
///
|
||||
@@ -720,7 +740,7 @@ pub fn cmd_comment(
|
||||
return Err(anyhow!("Could not determine ticket ID."));
|
||||
}
|
||||
|
||||
let comments_dir = worklane_dir.join("comments").join(&ticket_uuid);
|
||||
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
|
||||
fs::create_dir_all(&comments_dir)?;
|
||||
|
||||
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
|
||||
@@ -852,12 +872,23 @@ fn apply(content: &mut String, changed: &mut Vec<&'static str>, field: &'static
|
||||
}
|
||||
|
||||
fn report(fields: &[&str], title: &str, verb: &str) {
|
||||
report_in(fields, title, Color::Green, verb)
|
||||
}
|
||||
|
||||
/// The same, for a subject that is not a title.
|
||||
///
|
||||
/// Green means title, everywhere, so the one caller whose subject is a tag cannot use it:
|
||||
/// a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong, and green is deliberately
|
||||
/// not one of them. The colour is passed in rather than decided here, which is the trade
|
||||
/// `paint` makes with `color_text`, and it keeps the wording in one place so a tag reports
|
||||
/// a no-op in the same words a ticket does.
|
||||
fn report_in(fields: &[&str], title: &str, color: Color, verb: &str) {
|
||||
if fields.is_empty() {
|
||||
println!("No changes to '{}'", color_text(title, Color::Green));
|
||||
println!("No changes to '{}'", color_text(title, color));
|
||||
return;
|
||||
}
|
||||
|
||||
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, Color::Green));
|
||||
println!("{} {} on '{}'", verb, fields.join(", "), color_text(title, color));
|
||||
}
|
||||
|
||||
pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
@@ -1228,6 +1259,101 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Declare a tag, and what it means.
|
||||
///
|
||||
/// The counterpart of `cmd_tags`, which reports the vocabulary the tickets *carry*. This
|
||||
/// writes the one the board *intends*, and the two are deliberately not kept in step: a
|
||||
/// declaration tags nothing, so the file cannot be used to work out what is in use, and
|
||||
/// `tags add` on a word no ticket carries is the normal case rather than a mistake.
|
||||
///
|
||||
/// **A tag already declared is refused rather than overwritten**, the way `add` refuses
|
||||
/// nothing and `campaign set --codename` refuses a replacement without `--force`. An
|
||||
/// annotation is the sentence a whole team files tickets against, so replacing one by
|
||||
/// typing `add` twice is not something to do by accident. The refusal names the command
|
||||
/// that does replace it, since that is the next thing the caller wants.
|
||||
///
|
||||
/// The whole file is re-rendered from the parsed vocabulary, so declaring a tag also
|
||||
/// re-sorts the file and rewrites its preamble. That is why an unreadable file is an error
|
||||
/// in `TagIndex::load` rather than an empty vocabulary: here, empty would mean erased.
|
||||
pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let mut index = TagIndex::load(&worklane_dir)?;
|
||||
|
||||
if index.declared(&args.tag) {
|
||||
return Err(anyhow!(
|
||||
"Tag '{}' is already declared, so nothing was written. \
|
||||
Use `worklane tags set` to change what it means",
|
||||
args.tag
|
||||
));
|
||||
}
|
||||
|
||||
// Joined with a single newline, so an empty value is a paragraph break, exactly as it
|
||||
// is for a description.
|
||||
let annotation = trim_blank_ends(&args.annotation).join("\n");
|
||||
index.declare(&args.tag, &annotation);
|
||||
|
||||
write_then_replace(
|
||||
&worklane_dir,
|
||||
&tags_path(&worklane_dir),
|
||||
TAGS_FILE,
|
||||
&index.render(),
|
||||
TAG,
|
||||
&args.tag,
|
||||
)?;
|
||||
|
||||
// The tag in its own colour, which is the colour it is drawn in on every card and in
|
||||
// every listing: `tag_color` is a pure function of the word.
|
||||
println!("Declared tag: {}", color_text(&args.tag, tag_color(&args.tag)));
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Replace what a declared tag means.
|
||||
///
|
||||
/// The other half of `tags add`, and the half `campaign` still lacks for its description,
|
||||
/// 32e98ab. An annotation is the sentence a whole team files tickets against, so getting it
|
||||
/// wrong once must not be permanent.
|
||||
///
|
||||
/// **A tag that is not declared is refused rather than declared here.** `add` and `set` are
|
||||
/// a pair, each refusing what the other is for, so which of the two wrote a line is never a
|
||||
/// question of which one happened to be typed. The refusal names the other command, the way
|
||||
/// `add`'s names this one.
|
||||
///
|
||||
/// The no-op compares the rendered file rather than the annotation, which is what `apply`
|
||||
/// does for a ticket: the file is the thing that would be written, so it is the thing worth
|
||||
/// asking whether the write would change.
|
||||
pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let mut index = TagIndex::load(&worklane_dir)?;
|
||||
|
||||
if !index.declared(&args.tag) {
|
||||
return Err(anyhow!(
|
||||
"No tag '{}' is declared, so nothing was written. \
|
||||
Use `worklane tags add` to declare it",
|
||||
args.tag
|
||||
));
|
||||
}
|
||||
|
||||
let original = index.render();
|
||||
index.declare(&args.tag, &trim_blank_ends(&args.annotation).join("\n"));
|
||||
let next = index.render();
|
||||
|
||||
let mut changed: Vec<&'static str> = Vec::new();
|
||||
if original != next {
|
||||
changed.push("annotation");
|
||||
write_then_replace(
|
||||
&worklane_dir,
|
||||
&tags_path(&worklane_dir),
|
||||
TAGS_FILE,
|
||||
&next,
|
||||
TAG,
|
||||
&args.tag,
|
||||
)?;
|
||||
}
|
||||
|
||||
report_in(&changed, &args.tag, tag_color(&args.tag), "Updated");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Replace fields on a campaign that is already filed.
|
||||
///
|
||||
/// `cmd_set` for a campaign, and built out of the same parts: `set_title` for the heading,
|
||||
@@ -1551,9 +1677,38 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
|
||||
};
|
||||
|
||||
let root = install::skills_root()?;
|
||||
let written = install_each(&chosen, &root, force, |asset| {
|
||||
format!("worklane install-skill {} --print", asset.name)
|
||||
})?;
|
||||
|
||||
// Once, and only when something arrived: repeating it per document would make the
|
||||
// instruction look like part of each outcome rather than the one thing to do next.
|
||||
if written {
|
||||
println!("Claude Code and opencode pick it up on their next session");
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Write each asset under `root` and report what happened to it.
|
||||
///
|
||||
/// Shared by both install commands, which differ in what they install and in what they
|
||||
/// say afterwards, never in how an outcome is reported. `compare` is the invocation the
|
||||
/// refusal points at, which is the one line that has to name the command it came from.
|
||||
///
|
||||
/// Returns whether anything was written, because that is what decides the closing line:
|
||||
/// each command has its own thing to say about what picks the asset up, and neither
|
||||
/// should say it once per asset.
|
||||
fn install_each(
|
||||
chosen: &[&install::Asset],
|
||||
root: &Path,
|
||||
force: bool,
|
||||
compare: impl Fn(&install::Asset) -> String,
|
||||
) -> Result<bool> {
|
||||
let mut written = false;
|
||||
|
||||
for asset in chosen {
|
||||
match asset.install(&root, force)? {
|
||||
match asset.install(root, force)? {
|
||||
install::Outcome::Written(path) => {
|
||||
println!("Installed the {} {} to: {}", asset.name, asset.what, path.display());
|
||||
written = true;
|
||||
@@ -1563,18 +1718,41 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
|
||||
}
|
||||
install::Outcome::Refused(path) => {
|
||||
println!("Differs from the version in this binary: {}", path.display());
|
||||
println!(
|
||||
"Compare with `worklane install-skill {} --print`, or overwrite with --force",
|
||||
asset.name
|
||||
);
|
||||
println!("Compare with `{}`, or overwrite with --force", compare(asset));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Once, and only when something arrived: repeating it per document would make the
|
||||
// instruction look like part of each outcome rather than the one thing to do next.
|
||||
Ok(written)
|
||||
}
|
||||
|
||||
/// Install the opencode tool definitions.
|
||||
///
|
||||
/// No name argument, where `install-skill` has an optional one: there is a single tool
|
||||
/// file, so a name could only be right or wrong, and `--print` needs no help deciding
|
||||
/// what to print.
|
||||
pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
|
||||
if print {
|
||||
print!("{}", install::TOOL.content);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let chosen: Vec<&install::Asset> = install::TOOLS.iter().collect();
|
||||
let root = install::tools_root()?;
|
||||
let written =
|
||||
install_each(&chosen, &root, force, |_| "worklane install-tool --print".to_string())?;
|
||||
|
||||
// Not "on its next session", which is what the skills say: opencode reads its config
|
||||
// once at startup and does not reload it, so a running one keeps the tools it began
|
||||
// with. The second line is there because the file is executable and looks like it
|
||||
// needs a toolchain: it does not, it runs inside opencode.
|
||||
if written {
|
||||
println!("Claude Code and opencode pick it up on their next session");
|
||||
println!(
|
||||
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded"
|
||||
);
|
||||
println!(
|
||||
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine"
|
||||
);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
|
||||
+151
-4
@@ -11,9 +11,11 @@
|
||||
//! has learned the invocation should not have to learn a new name for each document
|
||||
//! added later, or the new one silently never arrives.
|
||||
//!
|
||||
//! The machinery is written once for both kinds of asset this repo will ship. The tool
|
||||
//! file for opencode is executable code needing Bun, so it gets its own command and its
|
||||
//! own root, but the compare-and-refuse logic is the same and lives here.
|
||||
//! The machinery is written once for both kinds of asset. The tool file is executable
|
||||
//! code and reaches opencode alone, so it gets its own command and its own root, but the
|
||||
//! compare-and-refuse logic is the same and lives here. What it needs at runtime is
|
||||
//! opencode and nothing else: it is loaded into opencode's own runtime, so neither Bun
|
||||
//! nor `@opencode-ai/plugin` has to be installed for the import in it to resolve.
|
||||
|
||||
use std::io;
|
||||
use std::path::{Path, PathBuf};
|
||||
@@ -73,6 +75,33 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
|
||||
pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
|
||||
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
|
||||
/// no directory it scans for one, so this is not the artifact that would reach it. That
|
||||
/// asymmetry is the whole reason it is its own command with its own root rather than a
|
||||
/// flag on `install-skill`.
|
||||
///
|
||||
/// Flat in the root rather than in a directory of its own, and the file name is load
|
||||
/// bearing: opencode builds each tool id as the file name then the export, so this file
|
||||
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
|
||||
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
|
||||
/// with; a tool carries it in the file name alone.
|
||||
pub const TOOL: Asset = Asset {
|
||||
name: "worklane",
|
||||
what: "tool",
|
||||
relative: "worklane.ts",
|
||||
content: include_str!("../assets/TOOL.ts"),
|
||||
};
|
||||
|
||||
/// Every tool this binary carries.
|
||||
///
|
||||
/// One, and an array anyway: it is what keeps the install loop the same shape as the
|
||||
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
|
||||
/// is one.
|
||||
pub static TOOLS: [Asset; 1] = [TOOL];
|
||||
|
||||
/// The skill a name on the command line asks for.
|
||||
pub fn skill_named(name: &str) -> Result<&'static Asset> {
|
||||
SKILLS
|
||||
@@ -106,6 +135,48 @@ pub fn skills_root() -> Result<PathBuf> {
|
||||
Ok(Path::new(&home).join(".claude/skills"))
|
||||
}
|
||||
|
||||
/// Where the tool has to sit for opencode to load it in every project.
|
||||
///
|
||||
/// `XDG_CONFIG_HOME` when it is set and non-empty, `~/.config` otherwise, which is what
|
||||
/// opencode itself resolves: `opencode debug paths` reports its config root under
|
||||
/// `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without.
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows for
|
||||
/// `NO_COLOR`. Checked against opencode 1.15.10.
|
||||
///
|
||||
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
|
||||
/// directory outside any project and registered all eleven worklane tools. The singular
|
||||
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
|
||||
/// and `skill(s)`.
|
||||
///
|
||||
/// One agent, unlike `skills_root`. Claude Code has no path that belongs here at all: a
|
||||
/// tool reaches it through an MCP server, which is a different artifact and not one this
|
||||
/// binary carries.
|
||||
pub fn tools_root() -> Result<PathBuf> {
|
||||
let xdg = std::env::var_os("XDG_CONFIG_HOME");
|
||||
let home = std::env::var_os("HOME");
|
||||
|
||||
opencode_tool_dir(xdg.as_deref().map(Path::new), home.as_deref().map(Path::new))
|
||||
}
|
||||
|
||||
/// `tools_root` with the two variables passed in rather than read.
|
||||
///
|
||||
/// The seam exists for the reason `colors_wanted` has one: both branches and the failure
|
||||
/// have to be reachable from a test, and a threaded test binary cannot mutate the process
|
||||
/// environment to reach them one at a time.
|
||||
fn opencode_tool_dir(xdg: Option<&Path>, home: Option<&Path>) -> Result<PathBuf> {
|
||||
if let Some(xdg) = xdg.filter(|value| !value.as_os_str().is_empty()) {
|
||||
return Ok(xdg.join("opencode/tool"));
|
||||
}
|
||||
|
||||
let home = home.ok_or_else(|| {
|
||||
anyhow!(
|
||||
"cannot tell where your opencode config lives because neither XDG_CONFIG_HOME nor HOME is set in the environment"
|
||||
)
|
||||
})?;
|
||||
|
||||
Ok(home.join(".config/opencode/tool"))
|
||||
}
|
||||
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
pub enum Outcome {
|
||||
Written(PathBuf),
|
||||
@@ -331,7 +402,7 @@ mod tests {
|
||||
/// Subcommands the skill has no business teaching: the board is interactive and
|
||||
/// belongs to a person, `install-skill` is how the document arrived, and `help`
|
||||
/// is clap's own.
|
||||
const NOT_FOR_AGENTS: [&str; 3] = ["tui", "install-skill", "help"];
|
||||
const NOT_FOR_AGENTS: [&str; 4] = ["tui", "install-skill", "install-tool", "help"];
|
||||
|
||||
/// The converse, and the one that goes stale on its own: a *new* subcommand absent
|
||||
/// from the skill is invisible to an agent, and nothing else would notice.
|
||||
@@ -417,4 +488,80 @@ mod tests {
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------ the tool --
|
||||
|
||||
/// `XDG_CONFIG_HOME` wins, because it is what opencode itself resolves its config
|
||||
/// root from: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with it set.
|
||||
#[test]
|
||||
fn the_tool_root_follows_xdg_config_home_when_it_is_set() {
|
||||
let root = opencode_tool_dir(Some(Path::new("/tmp/xdg")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/tmp/xdg/opencode/tool"));
|
||||
}
|
||||
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows, so
|
||||
/// a wrapper script that cleared an inherited one still lands in the home directory
|
||||
/// rather than at `/opencode/tool`.
|
||||
#[test]
|
||||
fn an_empty_xdg_config_home_falls_back_to_the_home_directory() {
|
||||
let root = opencode_tool_dir(Some(Path::new("")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
|
||||
let unset = opencode_tool_dir(None, Some(Path::new("/home/x")));
|
||||
assert_eq!(unset.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
}
|
||||
|
||||
/// Neither one set is the case that has to fail rather than guess: writing to a
|
||||
/// relative `.config/opencode/tool` would put the tool wherever the caller happened
|
||||
/// to be standing.
|
||||
#[test]
|
||||
fn neither_variable_set_is_an_error_rather_than_a_relative_path() {
|
||||
let error = opencode_tool_dir(None, None).unwrap_err().to_string();
|
||||
assert!(error.contains("XDG_CONFIG_HOME"), "{error}");
|
||||
assert!(error.contains("HOME"), "{error}");
|
||||
}
|
||||
|
||||
/// The file name is the tool id prefix, not decoration: opencode names each tool as
|
||||
/// the file then the export, so a renamed file renames all eleven tools and every
|
||||
/// permission rule that mentions one.
|
||||
#[test]
|
||||
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
|
||||
let root = opencode_tool_dir(None, Some(Path::new("/home/x"))).unwrap();
|
||||
|
||||
assert_eq!(TOOL.path(&root), Path::new("/home/x/.config/opencode/tool/worklane.ts"));
|
||||
assert_eq!(TOOL.relative, "worklane.ts");
|
||||
}
|
||||
|
||||
/// Every tool the file exports names a real subcommand.
|
||||
///
|
||||
/// The guard the fish completion lists already have, pointed the other way: this
|
||||
/// catches a tool wrapping a command that has been renamed or dropped, which would
|
||||
/// fail only when an agent finally called it. It cannot catch the reverse, a
|
||||
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
|
||||
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
|
||||
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
|
||||
#[test]
|
||||
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
|
||||
use clap::CommandFactory;
|
||||
|
||||
let commands: Vec<String> = crate::Cli::command()
|
||||
.get_subcommands()
|
||||
.map(|command| command.get_name().to_string())
|
||||
.collect();
|
||||
|
||||
let exported: Vec<&str> = TOOL
|
||||
.content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("export const "))
|
||||
.filter_map(|rest| rest.split_whitespace().next())
|
||||
.collect();
|
||||
|
||||
assert_eq!(exported.len(), 11, "{exported:?}");
|
||||
for name in exported {
|
||||
assert!(
|
||||
commands.iter().any(|command| command == name),
|
||||
"the wrapper exports {name:?}, which is not a subcommand: {commands:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+18
-6
@@ -7,6 +7,7 @@ mod command;
|
||||
mod completions;
|
||||
mod handlers;
|
||||
mod install;
|
||||
mod tag;
|
||||
mod tui;
|
||||
mod util;
|
||||
|
||||
@@ -78,10 +79,17 @@ fn main() -> Result<()> {
|
||||
}
|
||||
},
|
||||
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
|
||||
Some(Command::Tags) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_tags(&worklane_dir)
|
||||
}
|
||||
// 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)
|
||||
}
|
||||
Some(TagCommand::Add(args)) => cmd_tag_add(&args, &start),
|
||||
Some(TagCommand::Set(args)) => cmd_tag_set(&args, &start),
|
||||
},
|
||||
// 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 }) => {
|
||||
@@ -92,6 +100,9 @@ fn main() -> Result<()> {
|
||||
Some(Command::InstallSkill { skill, force, print }) => {
|
||||
cmd_install_skill(skill.as_deref(), force, print)
|
||||
}
|
||||
// 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),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -218,8 +229,9 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
KeyCode::Char('d') => board.toggle_done(screen),
|
||||
// An ordinary single-shot action like the rest: it opens the prompt, and
|
||||
// from the next keypress on `search_key` above has the keyboard. A `/`
|
||||
// typed into an open prompt is taken there as a character, so this arm
|
||||
// is only ever the way in.
|
||||
// typed into an open prompt is taken there as a character, and one pressed
|
||||
// at an open picker is taken by `picker_key` to open the picker's own
|
||||
// query, so this arm is only ever the way in to the board's prompt.
|
||||
KeyCode::Char('/') => board.open_search(),
|
||||
// `y` as in yank, for the readers this board is for, and the only letter
|
||||
// left that a vim hand would reach for. The clipboard is handed in rather
|
||||
|
||||
+312
@@ -0,0 +1,312 @@
|
||||
//! The tag vocabulary: which tags the board declares, and what each one means.
|
||||
//!
|
||||
//! One file, `.worklane/tags.md`, beside the status directories rather than among them,
|
||||
//! for the reason the campaigns directory sits there: a tag has no status. One section
|
||||
//! per tag, the tag as the heading and its annotation as the prose under it, so the file
|
||||
//! reads as a document to whoever opens it and parses by heading to the CLI.
|
||||
//!
|
||||
//! **Declaring a tag tags no ticket, and tagging a ticket declares nothing.** This is a
|
||||
//! vocabulary and not an index of what carries what: the counts stay derived from the
|
||||
//! status directories, where `cmd_tags` already reads them. So the file and the board can
|
||||
//! disagree, and that disagreement is the point — a tag carried but never declared is a
|
||||
//! word nobody agreed to, which is what `campaign` and `campaigns` on this board were.
|
||||
//!
|
||||
//! Unlike a campaign, a tag has no uuid and no file of its own. It *is* its name, which is
|
||||
//! what `ls --tag` matches whole and case sensitively, so the name is the key here and
|
||||
//! there is nothing to resolve by prefix.
|
||||
|
||||
use anyhow::{Result, anyhow};
|
||||
use std::collections::BTreeMap;
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use crate::util::trim_blank_ends;
|
||||
|
||||
/// The vocabulary file, beside the status directories rather than among them.
|
||||
pub const TAGS_FILE: &str = "tags.md";
|
||||
|
||||
pub fn tags_path(worklane_dir: &Path) -> PathBuf {
|
||||
worklane_dir.join(TAGS_FILE)
|
||||
}
|
||||
|
||||
/// What one tag's heading looks like, and therefore what an annotation may not start a
|
||||
/// line with.
|
||||
///
|
||||
/// Public so the `--annotation` parser refuses the one line that would split a section,
|
||||
/// rather than carrying its own copy of the spelling. Two places knowing what a heading
|
||||
/// is, is how the file comes to be written in a shape it cannot be read back in.
|
||||
pub const SECTION: &str = "## ";
|
||||
|
||||
/// What a tag declared with nothing to say about it writes.
|
||||
///
|
||||
/// A placeholder rather than an empty section, for the reason `add` writes one into an
|
||||
/// empty Description: a heading with nothing under it reads as a file that failed to
|
||||
/// write, and the round trip has nothing to be right about.
|
||||
pub const NO_ANNOTATION: &str = "_No annotation provided._";
|
||||
|
||||
/// The heading the file opens with. Not a tag: [`tag_heading`] only reads level two.
|
||||
const TITLE: &str = "# Tags";
|
||||
|
||||
/// What the file says for itself, for whoever opens it rather than for the parser.
|
||||
///
|
||||
/// Re-rendered on every write, so it is present whether `init` made the file or
|
||||
/// `tags add` did. It says what declaring does and does not do, because the file's one
|
||||
/// real trap is reading it as the list of tags in use.
|
||||
const PREAMBLE: &str = "\
|
||||
What each tag on this board means, and when it is appropriate to reach for it. Declaring a
|
||||
tag here tags nothing: the counts come from the tickets themselves, and `worklane tags` is
|
||||
what reports them. Written by `worklane tags`, not by hand.";
|
||||
|
||||
/// The tag a level-two heading names, or nothing for any other line.
|
||||
///
|
||||
/// Exactly two hashes. A `### ` line inside an annotation is prose about the tag it sits
|
||||
/// under and not the start of another one, which a bare `strip_prefix` would read as a tag
|
||||
/// called `# something`.
|
||||
fn tag_heading(line: &str) -> Option<&str> {
|
||||
let rest = line.strip_prefix(SECTION)?;
|
||||
|
||||
match rest.starts_with('#') {
|
||||
true => None,
|
||||
false => Some(rest.trim()),
|
||||
}
|
||||
}
|
||||
|
||||
/// The board's declared tags, each with what it means.
|
||||
///
|
||||
/// A `BTreeMap` rather than a `Vec`: the order is alphabetical by byte, which is the order
|
||||
/// `cmd_tags` already prints in, so `Bug` and `bug` stay two entries and land next to each
|
||||
/// other. Near-duplicates being adjacent is the property the whole file is for.
|
||||
///
|
||||
/// An annotation of `""` is a tag declared with nothing said about it, which is why the
|
||||
/// placeholder is a rendering detail rather than a value anything holds.
|
||||
#[derive(Default)]
|
||||
pub struct TagIndex {
|
||||
tags: BTreeMap<String, String>,
|
||||
}
|
||||
|
||||
impl TagIndex {
|
||||
/// The vocabulary as the file declares it.
|
||||
///
|
||||
/// A missing file is an empty vocabulary and not an error: every board made before this
|
||||
/// existed has none, and refusing there would mean a `worklane init` over a live board
|
||||
/// just to get a file.
|
||||
///
|
||||
/// An *unreadable* file is an error, which is the opposite of what [`CampaignIndex`]
|
||||
/// does with its directory, and deliberately. The whole file is re-rendered on every
|
||||
/// write, so treating one that is there as empty would erase every tag in it on the
|
||||
/// next `tags add`. A campaign index that comes back empty loses a label on a card;
|
||||
/// this one would lose the file.
|
||||
///
|
||||
/// [`CampaignIndex`]: crate::campaign::CampaignIndex
|
||||
pub fn load(worklane_dir: &Path) -> Result<Self> {
|
||||
let path = tags_path(worklane_dir);
|
||||
|
||||
if !path.exists() {
|
||||
return Ok(Self::default());
|
||||
}
|
||||
|
||||
let content = fs::read_to_string(&path).map_err(|e| {
|
||||
anyhow!("Could not read the tag vocabulary at {}: {}", path.display(), e)
|
||||
})?;
|
||||
|
||||
Ok(Self::parse(&content))
|
||||
}
|
||||
|
||||
/// The vocabulary out of the file's text.
|
||||
///
|
||||
/// Everything above the first tag heading is prose for whoever opens the file and is
|
||||
/// dropped: the title, the preamble, and anything else that ended up there. A heading
|
||||
/// with no tag in it starts nothing, and the lines under it belong to no tag, so a
|
||||
/// damaged file loses that section rather than attaching it to the tag above.
|
||||
pub fn parse(content: &str) -> Self {
|
||||
let mut tags = BTreeMap::new();
|
||||
let mut open: Option<(String, Vec<String>)> = None;
|
||||
|
||||
for line in content.lines() {
|
||||
match tag_heading(line) {
|
||||
Some(tag) => {
|
||||
if let Some((held, body)) = open.take() {
|
||||
tags.insert(held, annotation(&body));
|
||||
}
|
||||
if !tag.is_empty() {
|
||||
open = Some((tag.to_string(), Vec::new()));
|
||||
}
|
||||
}
|
||||
None => {
|
||||
if let Some((_, body)) = &mut open {
|
||||
body.push(line.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if let Some((held, body)) = open {
|
||||
tags.insert(held, annotation(&body));
|
||||
}
|
||||
|
||||
Self { tags }
|
||||
}
|
||||
|
||||
/// Whether the file already declares this tag, matched whole and case sensitively, the
|
||||
/// way `ls --tag` matches it.
|
||||
pub fn declared(&self, tag: &str) -> bool {
|
||||
self.tags.contains_key(tag)
|
||||
}
|
||||
|
||||
/// Declare `tag`, or replace what it means.
|
||||
///
|
||||
/// One writer for both, because the file holds one section per tag either way and the
|
||||
/// question of whether a caller may overwrite is the caller's: `tags add` refuses a tag
|
||||
/// already declared, and `tags set` refuses one that is not.
|
||||
pub fn declare(&mut self, tag: &str, annotation: &str) {
|
||||
self.tags.insert(tag.to_string(), annotation.to_string());
|
||||
}
|
||||
|
||||
/// The whole file, rendered from the whole vocabulary.
|
||||
///
|
||||
/// Every write goes through here rather than splicing one section in place, which is
|
||||
/// what keeps the file canonical: alphabetical, one blank line between sections, and
|
||||
/// the preamble present however the file came to exist. The cost is that nothing
|
||||
/// hand-written above the first heading survives a write, which is the bargain every
|
||||
/// file under `.worklane/` already makes — the CLI is its only writer.
|
||||
pub fn render(&self) -> String {
|
||||
let mut out = format!("{TITLE}\n\n{PREAMBLE}\n");
|
||||
|
||||
for (tag, annotation) in &self.tags {
|
||||
let body = match annotation.is_empty() {
|
||||
true => NO_ANNOTATION,
|
||||
false => annotation,
|
||||
};
|
||||
out.push_str(&format!("\n{SECTION}{tag}\n{body}\n"));
|
||||
}
|
||||
|
||||
out
|
||||
}
|
||||
}
|
||||
|
||||
/// One section's prose, with the blank lines around it dropped and the placeholder read
|
||||
/// back as nothing.
|
||||
///
|
||||
/// Through `trim_blank_ends`, the same function that decides where a ticket's description
|
||||
/// starts and ends, so a blank line inside an annotation is kept and one at either end is
|
||||
/// not.
|
||||
fn annotation(body: &[String]) -> String {
|
||||
let text = trim_blank_ends(body).join("\n");
|
||||
|
||||
match text == NO_ANNOTATION {
|
||||
true => String::new(),
|
||||
false => text,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// What a tag holds, read back out of the file it was written into. The round trip is
|
||||
/// the property that matters: nothing else keeps the writer and the parser agreeing on
|
||||
/// what a section is.
|
||||
fn round_trip(tag: &str, annotation: &str) -> String {
|
||||
let mut index = TagIndex::default();
|
||||
index.declare(tag, annotation);
|
||||
|
||||
let read = TagIndex::parse(&index.render());
|
||||
read.tags
|
||||
.get(tag)
|
||||
.cloned()
|
||||
.expect("the tag did not survive the round trip")
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_annotation_survives_the_round_trip() {
|
||||
assert_eq!(
|
||||
round_trip("bug", "Something the binary does wrong."),
|
||||
"Something the binary does wrong."
|
||||
);
|
||||
}
|
||||
|
||||
/// A blank line inside an annotation is a paragraph break and is kept, which is what
|
||||
/// `trim_blank_ends` is doing here rather than a blanket trim.
|
||||
#[test]
|
||||
fn a_paragraph_break_inside_an_annotation_is_kept() {
|
||||
assert_eq!(round_trip("bug", "One.\n\nTwo."), "One.\n\nTwo.");
|
||||
}
|
||||
|
||||
/// A tag declared with nothing to say writes the placeholder and reads back as nothing,
|
||||
/// so the file never holds a heading with a blank under it and nothing ever holds the
|
||||
/// placeholder as if it were prose.
|
||||
#[test]
|
||||
fn a_tag_with_no_annotation_writes_the_placeholder_and_reads_back_empty() {
|
||||
let mut index = TagIndex::default();
|
||||
index.declare("cli", "");
|
||||
|
||||
let rendered = index.render();
|
||||
assert!(rendered.contains(NO_ANNOTATION), "{rendered}");
|
||||
assert_eq!(TagIndex::parse(&rendered).tags["cli"], "");
|
||||
}
|
||||
|
||||
/// Byte order, so `Bug` and `bug` are two tags and sit next to each other. The same
|
||||
/// order `tags` prints in, and the reason the file is worth reading at all: a
|
||||
/// near-duplicate is spotted by being adjacent to what it duplicates.
|
||||
#[test]
|
||||
fn the_file_is_alphabetical_and_keeps_case_apart() {
|
||||
let mut index = TagIndex::default();
|
||||
for tag in ["tui", "bug", "Bug", "cli"] {
|
||||
index.declare(tag, "");
|
||||
}
|
||||
|
||||
let rendered = index.render();
|
||||
let headings: Vec<&str> = rendered.lines().filter_map(tag_heading).collect();
|
||||
assert_eq!(headings, vec!["Bug", "bug", "cli", "tui"]);
|
||||
}
|
||||
|
||||
/// Everything above the first heading is for whoever opens the file. The preamble says
|
||||
/// `## ` nowhere, but a parser that took the title for a tag would declare one called
|
||||
/// `Tags` on the next write.
|
||||
#[test]
|
||||
fn the_prose_above_the_first_heading_declares_nothing() {
|
||||
let index = TagIndex::parse(&TagIndex::default().render());
|
||||
assert!(index.tags.is_empty(), "the preamble declared a tag");
|
||||
}
|
||||
|
||||
/// A deeper heading is prose about the tag it sits under. `strip_prefix` alone read it
|
||||
/// as a tag called `# whatever`, which then became a real section on the next write.
|
||||
#[test]
|
||||
fn a_deeper_heading_inside_an_annotation_is_not_a_tag() {
|
||||
let index = TagIndex::parse("# Tags\n\n## bug\nProse.\n\n### An aside\nMore prose.\n");
|
||||
|
||||
assert_eq!(index.tags.len(), 1, "a sub-heading was read as a tag");
|
||||
assert_eq!(index.tags["bug"], "Prose.\n\n### An aside\nMore prose.");
|
||||
}
|
||||
|
||||
/// A heading naming nothing starts no section, and takes the lines under it with it
|
||||
/// rather than attaching them to the tag above.
|
||||
#[test]
|
||||
fn an_empty_heading_declares_nothing_and_swallows_its_own_body() {
|
||||
let index = TagIndex::parse("## bug\nProse.\n\n## \nOrphaned.\n");
|
||||
|
||||
assert_eq!(index.tags.len(), 1);
|
||||
assert_eq!(index.tags["bug"], "Prose.");
|
||||
}
|
||||
|
||||
/// A board that never had the file has an empty vocabulary rather than an error: every
|
||||
/// board made before this existed is in that state.
|
||||
#[test]
|
||||
fn a_board_with_no_file_has_no_tags() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
assert!(TagIndex::load(dir.path()).unwrap().tags.is_empty());
|
||||
}
|
||||
|
||||
/// And a file that is there but cannot be read is an error, not an empty vocabulary.
|
||||
/// The whole file is re-rendered on every write, so empty here would mean erased on the
|
||||
/// next `tags add`.
|
||||
#[test]
|
||||
fn a_file_that_cannot_be_read_is_an_error_rather_than_an_empty_vocabulary() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
// A directory where the file should be: `read_to_string` fails on it, which a
|
||||
// missing file does not, so this is the path the error is actually for.
|
||||
fs::create_dir(tags_path(dir.path())).unwrap();
|
||||
|
||||
assert!(TagIndex::load(dir.path()).is_err());
|
||||
}
|
||||
}
|
||||
+1365
-97
File diff suppressed because it is too large
Load Diff
+608
-31
@@ -16,6 +16,32 @@ pub const TIMESTAMP_FORMAT: &str = "%Y-%m-%d %H:%M:%S";
|
||||
/// Fixed width, so the lexicographic sort in `read_comments` stays chronological.
|
||||
pub const COMMENT_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
|
||||
|
||||
/// Where a ticket's comments live, under the board.
|
||||
///
|
||||
/// Beside the status directories rather than among them, the way `campaigns_dir` is: a
|
||||
/// comment has no status of its own. Spelled once here, so the writer, the reader and the
|
||||
/// card's counter cannot disagree about the path.
|
||||
pub const COMMENTS_DIR: &str = "comments";
|
||||
|
||||
/// The comments directory for one ticket, named by its full uuid.
|
||||
pub fn comments_dir(board: &Path, uuid: &str) -> std::path::PathBuf {
|
||||
board.join(COMMENTS_DIR).join(uuid)
|
||||
}
|
||||
|
||||
/// The mark a card puts after its comment count.
|
||||
///
|
||||
/// A closing quotation ornament, so `2\u{275e}` reads as two things somebody said rather
|
||||
/// than as a second bracketed counter beside the criteria.
|
||||
///
|
||||
/// Deliberately neither U+1F4AC SPEECH BALLOON nor U+1F5E8 LEFT SPEECH BUBBLE. The first
|
||||
/// has emoji presentation and East Asian Width Wide, so it draws two cells where
|
||||
/// `spans_width` counts one character and every corner on the card would be a cell out.
|
||||
/// The second is text presentation and Neutral, but sits in a pictograph block most
|
||||
/// terminal fonts leave as tofu. This one is a Dingbat, with the coverage the priority
|
||||
/// meter's Geometric Shapes have, and Neutral, so it is one cell wherever `BLOCKED_MARK`
|
||||
/// already is.
|
||||
pub const COMMENT_MARK: &str = "\u{275e}";
|
||||
|
||||
/// Whether colour is wanted, from the three inputs that decide it.
|
||||
///
|
||||
/// Split out from the caching wrapper so it can be tested without a pty and
|
||||
@@ -254,13 +280,87 @@ pub fn color_text(text: &str, color: Color) -> String {
|
||||
paint(text, color, should_use_colors())
|
||||
}
|
||||
|
||||
/// What sits at a candidate `.worklane` path.
|
||||
///
|
||||
/// The distinction the walk turns on is between nothing there and something
|
||||
/// unusable there. `exists()` follows a link, so a dangling one answered the same
|
||||
/// as an empty parent and the walk carried on upward until it met a board above
|
||||
/// the project, which then became the board every write went to. Silently. With
|
||||
/// the boards kept outside the project a dangling link is an ordinary state
|
||||
/// rather than a corrupted tree: it is what you have before the boards repo is
|
||||
/// cloned, and after a board directory is renamed.
|
||||
#[derive(Debug, PartialEq)]
|
||||
enum Candidate {
|
||||
/// Nothing at that path, which is the one answer the walk carries on from.
|
||||
Absent,
|
||||
/// A directory, or a link that resolves to one.
|
||||
Board,
|
||||
/// A link that resolves to nothing, carrying the target it names.
|
||||
Dangling(std::path::PathBuf),
|
||||
/// There, and not a directory: a regular file, or a link to one.
|
||||
NotADirectory,
|
||||
}
|
||||
|
||||
/// Which of the four a `.worklane` path is.
|
||||
///
|
||||
/// `symlink_metadata` first, so the answer is about the entry itself and absence
|
||||
/// cannot be confused with a target that is gone. Only then is the link followed,
|
||||
/// which is what makes a resolvable one indistinguishable from a real directory.
|
||||
fn classify(path: &Path) -> Result<Candidate> {
|
||||
let entry = match fs::symlink_metadata(path) {
|
||||
Ok(entry) => entry,
|
||||
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Candidate::Absent),
|
||||
// Anything other than absence is a filesystem that could not answer, and
|
||||
// reading that as absence is how the walk-past worked in the first place.
|
||||
Err(error) => return Err(anyhow!("Could not read {}: {error}", path.display())),
|
||||
};
|
||||
|
||||
if !entry.is_symlink() {
|
||||
return Ok(match entry.is_dir() {
|
||||
true => Candidate::Board,
|
||||
false => Candidate::NotADirectory,
|
||||
});
|
||||
}
|
||||
|
||||
// Read whether or not it resolves: the target is the only part of the failure
|
||||
// that says what to go and fix.
|
||||
let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf());
|
||||
|
||||
Ok(match fs::metadata(path) {
|
||||
Ok(resolved) if resolved.is_dir() => Candidate::Board,
|
||||
Ok(_) => Candidate::NotADirectory,
|
||||
Err(_) => Candidate::Dangling(target),
|
||||
})
|
||||
}
|
||||
|
||||
/// The first `.worklane` at or above `start`.
|
||||
///
|
||||
/// The symlink stays unresolved in what is returned, so a board reached through a
|
||||
/// link is the same path to everything downstream as one sitting in the project.
|
||||
pub fn find_worklane_dir(start: &Path) -> Result<std::path::PathBuf> {
|
||||
let mut current = start.canonicalize()?;
|
||||
|
||||
loop {
|
||||
let worklane_dir = current.join(".worklane");
|
||||
if worklane_dir.exists() {
|
||||
return Ok(worklane_dir);
|
||||
match classify(&worklane_dir)? {
|
||||
Candidate::Board => return Ok(worklane_dir),
|
||||
// The only answer that hands the search upward. A `.worklane` that is
|
||||
// there but unusable is this project's board and is reported here,
|
||||
// rather than quietly becoming a write to whatever sits above it.
|
||||
Candidate::Absent => {}
|
||||
Candidate::Dangling(target) => {
|
||||
return Err(anyhow!(
|
||||
"{} is a symlink to {}, which does not exist. The boards repo may not be cloned on this machine.",
|
||||
worklane_dir.display(),
|
||||
target.display()
|
||||
));
|
||||
}
|
||||
Candidate::NotADirectory => {
|
||||
return Err(anyhow!(
|
||||
"{} is not a directory. A board is a directory of ticket files.",
|
||||
worklane_dir.display()
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
if !current.pop() {
|
||||
@@ -1364,28 +1464,38 @@ pub const COMMITTED_ON_FIELD: &str = "Committed On";
|
||||
pub const SUBMITTED_ON_FIELD: &str = "Submitted On";
|
||||
pub const COMPLETED_ON_FIELD: &str = "Completed On";
|
||||
|
||||
/// Stamp the field of the status being entered and drop the other two.
|
||||
/// Stamp the field of the status being entered and drop the ones after it.
|
||||
///
|
||||
/// A stamp is present exactly while the ticket sits in its status, so the three are
|
||||
/// mutually exclusive: entering writes one, leaving removes it, and re-entering
|
||||
/// restamps rather than keeping the first value. That is what keeps a ticket moved
|
||||
/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is
|
||||
/// the line between these fields and d4ce964's history log. Metadata carries current
|
||||
/// state, which is why `Status` is a field at all; the trail of how the ticket got here
|
||||
/// belongs to the log, and a stamp left behind would be a second copy of that job.
|
||||
/// The stamps accumulate down the flow rather than being mutually exclusive, so a
|
||||
/// ticket that has walked the whole way carries `Created At`, `Committed On`,
|
||||
/// `Submitted On` and `Completed On` side by side and the journey behind it is legible.
|
||||
/// Presence therefore means the ticket got that far and has not been sent back past it,
|
||||
/// not that it is sitting there now; `Status` is what says where it is.
|
||||
///
|
||||
/// One arrival rule covers both directions. A backward move truncates the journey at
|
||||
/// the target, so `done` back to `reviewing` drops `Completed On` and keeps the two
|
||||
/// before it, and anything back to `backlog` drops all three. A forward skip under `-f`
|
||||
/// has nothing after it to clear, so `backlog` straight to `done` stamps `Completed On`
|
||||
/// alone and leaves the stages it jumped over unwritten rather than fabricated.
|
||||
/// Re-entering restamps rather than keeping the earlier value.
|
||||
///
|
||||
/// This is still not d4ce964's history log. These fields answer how far and when, once
|
||||
/// per stage; every status change, every owner and every tag along the way is the log's
|
||||
/// job and must not be grown here. `backlog` has no stamp, `Created At` answers for it.
|
||||
///
|
||||
/// The time comes in as a string rather than being read here, so the caller stamps the
|
||||
/// same moment it reports and a test can pin the value.
|
||||
pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result<String> {
|
||||
let mut content = content.to_string();
|
||||
|
||||
// Every status but the target, so a skipping move under `-f` clears the stamps of
|
||||
// the stages it jumped over as well as the one it left.
|
||||
for status in Status::ALL {
|
||||
if status == target {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Every status after the target, off the flow order `Status::ALL` already holds
|
||||
// rather than a case per move, so arrival alone decides what is cleared and a
|
||||
// backward move and a skip are the same rule.
|
||||
for status in Status::ALL
|
||||
.iter()
|
||||
.skip_while(|status| **status != target)
|
||||
.skip(1)
|
||||
{
|
||||
let Some(field) = status.stamp_field() else {
|
||||
continue;
|
||||
};
|
||||
@@ -2496,8 +2606,8 @@ pub enum Status {
|
||||
}
|
||||
|
||||
impl Status {
|
||||
/// Every status, in flow order. The one list, which [`status_dirs`] and `mv` both
|
||||
/// read rather than spelling the four names again.
|
||||
/// Every status, in flow order. The one list, which [`status_dirs`], `mv` and every
|
||||
/// caller of [`by_status_order`] read rather than spelling the four names again.
|
||||
pub const ALL: [Status; 4] = [
|
||||
Status::Backlog,
|
||||
Status::Committed,
|
||||
@@ -2650,9 +2760,59 @@ pub struct TicketItem {
|
||||
/// malformed ticket is the worse failure, and is the same exception `detail_of`
|
||||
/// already makes.
|
||||
pub blockers: Vec<String>,
|
||||
/// How many comments the ticket carries, `0` for one with none.
|
||||
///
|
||||
/// Read here for the reason `criteria` is: the board draws it on every card, so
|
||||
/// asking per card would mean a `read_dir` per ticket per frame. It is the one field
|
||||
/// on this pass that costs a directory listing rather than coming off the content
|
||||
/// already in hand, which is why it is counted and never read: the bodies are the
|
||||
/// detail view's business, and a count needs none of them.
|
||||
pub comments: usize,
|
||||
/// The file this came from. The listing ignores it; the TUI opens it for the
|
||||
/// detail view rather than resolving the ticket a second time.
|
||||
pub path: std::path::PathBuf,
|
||||
/// The time `mv` stamped on entering committed, or `None` for a ticket that has
|
||||
/// never got that far.
|
||||
///
|
||||
/// Read here for the reason `criteria` is, and it is what its column is ordered by:
|
||||
/// a comparator that read the file would re-read every ticket on every comparison,
|
||||
/// where this pass reads each one once.
|
||||
pub committed_on: Option<String>,
|
||||
/// The same for reviewing.
|
||||
pub submitted_on: Option<String>,
|
||||
/// The same for done.
|
||||
pub completed_on: Option<String>,
|
||||
}
|
||||
|
||||
impl TicketItem {
|
||||
/// The stamp the ticket entered a status with, which is what that column sorts on.
|
||||
///
|
||||
/// 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.
|
||||
fn entry_stamp(&self, status: Status) -> Option<&str> {
|
||||
match status {
|
||||
Status::Backlog => None,
|
||||
Status::Committed => self.committed_on.as_deref(),
|
||||
Status::Reviewing => self.submitted_on.as_deref(),
|
||||
Status::Done => self.completed_on.as_deref(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The stamp a ticket carries for a status, or `None` for one it has not reached.
|
||||
///
|
||||
/// The field name comes off [`Status::stamp_field`], so what is read here cannot drift
|
||||
/// from what `mv` writes. An absent field reads as `_Not set_` like every other, and a
|
||||
/// stamp is machine-written so that spelling never appears as a value; both count as no
|
||||
/// stamp rather than as a time.
|
||||
fn parse_stamp(content: &str, status: Status) -> Option<String> {
|
||||
let value = parse_ticket_field(content, status.stamp_field()?);
|
||||
match is_unknown_value(&value) {
|
||||
true => None,
|
||||
false => Some(value),
|
||||
}
|
||||
}
|
||||
|
||||
/// The date part of a due value, for a view with only a corner to spend on it.
|
||||
@@ -2760,7 +2920,31 @@ pub fn display_ticket_items(items: &[TicketItem]) {
|
||||
}
|
||||
}
|
||||
|
||||
/// How many comments a ticket has, counted off the directory rather than read.
|
||||
///
|
||||
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
|
||||
/// not counted as something somebody wrote. A missing directory is none, which is what a
|
||||
/// ticket nobody has commented on has: no directory is created until the first comment.
|
||||
fn count_comments(board: &Path, uuid: &str) -> usize {
|
||||
let Ok(entries) = fs::read_dir(comments_dir(board, uuid)) else {
|
||||
return 0;
|
||||
};
|
||||
|
||||
entries
|
||||
.filter_map(|entry| entry.ok())
|
||||
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
|
||||
.count()
|
||||
}
|
||||
|
||||
pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketItem>> {
|
||||
let status_path = status_path.as_ref();
|
||||
// The comments sit beside the status directories, so the board is this one's parent.
|
||||
// Derived rather than taken as a second argument: every caller joins a status onto a
|
||||
// board it already holds, and two arguments would let a status from one board arrive
|
||||
// with the comments of another. `None` only for a bare relative path, which no caller
|
||||
// passes and which counts nothing rather than failing.
|
||||
let board = status_path.parent();
|
||||
|
||||
let entries: Vec<_> = fs::read_dir(status_path)?
|
||||
.filter_map(|e| e.ok())
|
||||
// A status directory is a plain directory, so anything can be dropped in it.
|
||||
@@ -2801,6 +2985,11 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
}),
|
||||
};
|
||||
|
||||
// The ticket's own ID field, not the filename stem: a comment directory is
|
||||
// named by the uuid the file records, which is what `comment` wrote it under.
|
||||
let uuid = parse_ticket_field(&content, "ID");
|
||||
let comments = board.map_or(0, |board| count_comments(board, &uuid));
|
||||
|
||||
Some(TicketItem {
|
||||
title,
|
||||
owner,
|
||||
@@ -2811,9 +3000,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
criteria: progress,
|
||||
campaign: parse_campaign(&content),
|
||||
tags: parse_tags(&content),
|
||||
uuid: parse_ticket_field(&content, "ID"),
|
||||
uuid,
|
||||
blockers,
|
||||
comments,
|
||||
path: e.path(),
|
||||
committed_on: parse_stamp(&content, Status::Committed),
|
||||
submitted_on: parse_stamp(&content, Status::Reviewing),
|
||||
completed_on: parse_stamp(&content, Status::Done),
|
||||
})
|
||||
})
|
||||
.collect();
|
||||
@@ -2822,11 +3015,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// The order a status column is read in: priority first, title as the tiebreak.
|
||||
/// The order the backlog is read in, and the tiebreak every other 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 the order the listing uses. A merge sorted a second way
|
||||
/// would put a p1 below a p5 depending on which project it came from.
|
||||
/// one and has to land in one order. A merge sorted a second way would put a p1 below a
|
||||
/// p5 depending on which project it came from, and the merge spans statuses, so no
|
||||
/// single stamp governs it.
|
||||
pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
|
||||
a.priority
|
||||
.rank()
|
||||
@@ -2834,6 +3029,39 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
|
||||
.then_with(|| a.title.to_lowercase().cmp(&b.title.to_lowercase()))
|
||||
}
|
||||
|
||||
/// 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, the way a changelog reads.
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// 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.
|
||||
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)) {
|
||||
(Some(left), Some(right)) => match status {
|
||||
Status::Done => 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.
|
||||
(None, None) => std::cmp::Ordering::Equal,
|
||||
};
|
||||
|
||||
by_stamp.then_with(|| by_priority_then_title(a, b))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -3241,6 +3469,50 @@ mod tests {
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// The count is a directory listing rather than a read: nothing here parses a comment,
|
||||
/// and the bodies are the detail view's business.
|
||||
///
|
||||
/// `.md` only, the filter `read_comments` applies, so a stray file dropped in there is
|
||||
/// not counted as something somebody wrote. A ticket with no directory at all has
|
||||
/// none, which is every ticket until the first comment creates one.
|
||||
#[test]
|
||||
fn collect_ticket_items_counts_the_comments_under_the_board() {
|
||||
let board = tempfile::tempdir().unwrap();
|
||||
let backlog = board.path().join("backlog");
|
||||
fs::create_dir_all(&backlog).unwrap();
|
||||
|
||||
let write = |uuid: &str| {
|
||||
fs::write(
|
||||
backlog.join(format!("{uuid}.md")),
|
||||
format!("# T{uuid}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Owner**: alice\n"),
|
||||
)
|
||||
.unwrap();
|
||||
};
|
||||
let talked_about = "11111111-0000-4000-8000-000000000001";
|
||||
let quiet = "11111111-0000-4000-8000-000000000002";
|
||||
write(talked_about);
|
||||
write(quiet);
|
||||
|
||||
let comments = comments_dir(board.path(), talked_about);
|
||||
fs::create_dir_all(&comments).unwrap();
|
||||
fs::write(comments.join("20260823_120000_000000.md"), "**Comment**\n").unwrap();
|
||||
fs::write(comments.join("20260823_120001_000000.md"), "**Comment**\n").unwrap();
|
||||
// Not a comment, and not counted as one.
|
||||
fs::write(comments.join("notes.txt"), "scratch\n").unwrap();
|
||||
|
||||
let items = collect_ticket_items(&backlog).unwrap();
|
||||
let counted = |uuid: &str| {
|
||||
items
|
||||
.iter()
|
||||
.find(|item| item.uuid == uuid)
|
||||
.unwrap_or_else(|| panic!("no item for {uuid}"))
|
||||
.comments
|
||||
};
|
||||
|
||||
assert_eq!(counted(talked_about), 2);
|
||||
assert_eq!(counted(quiet), 0);
|
||||
}
|
||||
|
||||
/// The blockers come off the read that builds the item, so the board pays no second
|
||||
/// pass for them, and only the `blocked by` kind is one: the other two record no
|
||||
/// dependency and gate nothing.
|
||||
@@ -3403,10 +3675,10 @@ mod tests {
|
||||
assert!(error.to_string().contains("Campaign"), "{error}");
|
||||
}
|
||||
|
||||
/// The one stamp the target status carries, and nothing of the others: the fields
|
||||
/// are current state, not a record of every stage the ticket has been through.
|
||||
/// The stamp of the status being entered, added to what the ticket already carries:
|
||||
/// the fields accumulate down the flow, so the stages behind it stay readable.
|
||||
#[test]
|
||||
fn entering_a_status_stamps_its_field_and_clears_the_rest() {
|
||||
fn entering_a_status_stamps_its_field_and_keeps_the_ones_before_it() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n",
|
||||
);
|
||||
@@ -3415,25 +3687,64 @@ mod tests {
|
||||
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(!updated.contains("**Committed On**"), "{updated}");
|
||||
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket
|
||||
/// carrying none rather than a Completed On for work it has undone.
|
||||
/// Arrival truncates the journey at the target, so the stage the ticket has been
|
||||
/// sent back out of is dropped and the ones it still got through are not.
|
||||
#[test]
|
||||
fn arriving_removes_the_stamps_of_the_statuses_after_the_target() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
);
|
||||
|
||||
let updated =
|
||||
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(!updated.contains("**Completed On**"), "{updated}");
|
||||
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
|
||||
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own and every status follows it, so a ticket forced
|
||||
/// all the way back carries none of the three rather than a trail it has undone.
|
||||
#[test]
|
||||
fn moving_back_to_backlog_leaves_no_stamp_behind() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n",
|
||||
"- **ID**: abc\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
);
|
||||
|
||||
let updated =
|
||||
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(!updated.contains("**Completed On**"), "{updated}");
|
||||
for field in [COMMITTED_ON_FIELD, SUBMITTED_ON_FIELD, COMPLETED_ON_FIELD] {
|
||||
assert!(!updated.contains(&format!("**{}**", field)), "{updated}");
|
||||
}
|
||||
assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}");
|
||||
}
|
||||
|
||||
/// A skip stamps the target and nothing else. The stages it jumped over are left
|
||||
/// unwritten rather than given a time the ticket never spent there.
|
||||
#[test]
|
||||
fn a_forward_skip_stamps_only_the_status_it_lands_in() {
|
||||
let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n");
|
||||
|
||||
let updated = set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(updated.contains("- **Completed On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(!updated.contains("**Committed On**"), "{updated}");
|
||||
assert!(!updated.contains("**Submitted On**"), "{updated}");
|
||||
}
|
||||
|
||||
/// Re-entry is the time of the move that brought it back, not the first one.
|
||||
#[test]
|
||||
fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() {
|
||||
@@ -3472,6 +3783,171 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
/// A listed ticket with only the fields the column order reads: its title, its
|
||||
/// priority and the stamp for the status being sorted.
|
||||
fn listed(title: &str, level: u8, status: Status, stamp: Option<&str>) -> TicketItem {
|
||||
let stamp = stamp.map(|value| value.to_string());
|
||||
|
||||
TicketItem {
|
||||
title: title.to_string(),
|
||||
owner: NOT_SET.to_string(),
|
||||
due: NOT_SET.to_string(),
|
||||
id: "0000000".to_string(),
|
||||
created: String::new(),
|
||||
priority: Priority::Level(level),
|
||||
criteria: None,
|
||||
campaign: None,
|
||||
tags: Vec::new(),
|
||||
uuid: NOT_SET.to_string(),
|
||||
blockers: Vec::new(),
|
||||
comments: 0,
|
||||
path: std::path::PathBuf::new(),
|
||||
committed_on: match status {
|
||||
Status::Committed => stamp.clone(),
|
||||
_ => None,
|
||||
},
|
||||
submitted_on: match status {
|
||||
Status::Reviewing => stamp.clone(),
|
||||
_ => None,
|
||||
},
|
||||
completed_on: match status {
|
||||
Status::Done => stamp,
|
||||
_ => 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> {
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
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.
|
||||
#[test]
|
||||
fn the_backlog_keeps_priority_then_title() {
|
||||
let items = vec![
|
||||
listed("zebra", 5, Status::Backlog, None),
|
||||
listed("alpha", 1, Status::Backlog, None),
|
||||
listed("beta", 1, Status::Backlog, None),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Backlog, items), ["alpha", "beta", "zebra"]);
|
||||
}
|
||||
|
||||
/// Committed and reviewing are queues: the head is what has waited longest, which is
|
||||
/// where the reader picks next from.
|
||||
#[test]
|
||||
fn committed_and_reviewing_list_the_oldest_stamp_first() {
|
||||
for status in [Status::Committed, Status::Reviewing] {
|
||||
let items = vec![
|
||||
listed("newest", 1, status, Some("2026-08-03 09:00:00")),
|
||||
listed("oldest", 5, status, Some("2026-08-01 09:00:00")),
|
||||
listed("middle", 1, status, Some("2026-08-02 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(status, items), ["oldest", "middle", "newest"], "{status:?}");
|
||||
}
|
||||
}
|
||||
|
||||
/// Done reads like a changelog: what just landed is at the top, and priority no
|
||||
/// longer decides anything about finished work.
|
||||
#[test]
|
||||
fn done_lists_the_newest_stamp_first() {
|
||||
let items = vec![
|
||||
listed("first", 1, Status::Done, Some("2026-08-01 09:00:00")),
|
||||
listed("last", 5, Status::Done, Some("2026-08-03 09:00:00")),
|
||||
listed("middle", 1, Status::Done, Some("2026-08-02 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Done, items), ["last", "middle", "first"]);
|
||||
}
|
||||
|
||||
/// A missing stamp is unknown, not ancient. Reading absence as the epoch would come
|
||||
/// free from the string comparison and hand the head of the queue to every legacy
|
||||
/// ticket, so it sinks instead, in both directions.
|
||||
#[test]
|
||||
fn a_ticket_with_no_stamp_sorts_below_every_stamped_one() {
|
||||
for status in [Status::Committed, Status::Reviewing, Status::Done] {
|
||||
let items = vec![
|
||||
listed("unstamped", 1, status, None),
|
||||
listed("stamped", 5, status, Some("2026-08-01 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(status, items), ["stamped", "unstamped"], "{status:?}");
|
||||
}
|
||||
}
|
||||
|
||||
/// `mv` writes whole seconds, so two moves in the same second is a real tie rather
|
||||
/// than a hypothetical one, and it falls through to the order the backlog uses.
|
||||
#[test]
|
||||
fn equal_stamps_fall_back_to_priority_then_title() {
|
||||
let same = Some("2026-08-01 09:00:00");
|
||||
let items = vec![
|
||||
listed("zebra", 1, Status::Committed, same),
|
||||
listed("beta", 3, Status::Committed, same),
|
||||
listed("alpha", 3, Status::Committed, same),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Committed, items), ["zebra", "alpha", "beta"]);
|
||||
}
|
||||
|
||||
/// Two unstamped tickets in one column are ordered among themselves the way the
|
||||
/// backlog is, rather than left in whatever order the directory handed them back.
|
||||
#[test]
|
||||
fn unstamped_tickets_are_ordered_among_themselves_by_priority_then_title() {
|
||||
let items = vec![
|
||||
listed("zebra", 1, Status::Done, None),
|
||||
listed("beta", 3, Status::Done, None),
|
||||
listed("alpha", 3, Status::Done, None),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Done, items), ["zebra", "alpha", "beta"]);
|
||||
}
|
||||
|
||||
/// The stamps come off the pass that builds the listing, not off a second read at
|
||||
/// comparison time, which is what makes an ordered column cost one read per file.
|
||||
#[test]
|
||||
fn collect_ticket_items_reads_the_stamps_the_order_sorts_on() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-stamps-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
fs::write(
|
||||
dir.join("aaaa_walked.md"),
|
||||
"# Walked\n\n## Metadata\n\n\
|
||||
- **ID**: aaaa\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
)
|
||||
.unwrap();
|
||||
fs::write(
|
||||
dir.join("bbbb_fresh.md"),
|
||||
"# Fresh\n\n## Metadata\n\n- **ID**: bbbb\n- **Status**: backlog\n",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let items = collect_ticket_items(&dir).unwrap();
|
||||
|
||||
let walked = items.iter().find(|item| item.title == "Walked").unwrap();
|
||||
assert_eq!(walked.committed_on.as_deref(), Some("2026-08-01 09:00:00"));
|
||||
assert_eq!(walked.submitted_on.as_deref(), Some("2026-08-02 09:00:00"));
|
||||
assert_eq!(walked.completed_on.as_deref(), Some("2026-08-03 09:00:00"));
|
||||
|
||||
// Absent reads as no stamp rather than as the `_Not set_` every other field
|
||||
// falls back to, so the order sinks it instead of comparing that text.
|
||||
let fresh = items.iter().find(|item| item.title == "Fresh").unwrap();
|
||||
assert_eq!(fresh.committed_on, None);
|
||||
assert_eq!(fresh.submitted_on, None);
|
||||
assert_eq!(fresh.completed_on, None);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// Removal is scoped to the section for the same reason the write is: a description
|
||||
/// quoting a field marker is prose, and rewriting it would corrupt the ticket text
|
||||
/// while leaving the real field in place.
|
||||
@@ -4484,4 +4960,105 @@ mod tests {
|
||||
"{rendered:?}"
|
||||
);
|
||||
}
|
||||
|
||||
// ----------------------------------------------------- finding the board --
|
||||
|
||||
/// A project directory under a temp root.
|
||||
///
|
||||
/// The root is canonicalized because `find_worklane_dir` canonicalizes its
|
||||
/// start: on a system whose temp path runs through a link, the two spellings
|
||||
/// of the same directory would not compare equal.
|
||||
fn project_in(root: &tempfile::TempDir) -> std::path::PathBuf {
|
||||
let dir = root.path().canonicalize().unwrap().join("project");
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
|
||||
/// The failure names the target, since the link is not the thing to fix, and it
|
||||
/// does not say to run `init`: that answer belongs to an empty tree, and giving
|
||||
/// it here points at the wrong problem.
|
||||
#[test]
|
||||
fn a_dangling_board_link_is_reported_with_its_target() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let target = project.parent().unwrap().join("boards/2fed877-the-board");
|
||||
std::os::unix::fs::symlink(&target, project.join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains(&target.display().to_string()), "{error}");
|
||||
assert!(error.contains("boards repo"), "{error}");
|
||||
assert!(!error.contains("worklane init"), "{error}");
|
||||
}
|
||||
|
||||
/// The bug this was written for: `exists()` follows the link, so a dangling one
|
||||
/// answered false, the walk carried on up the tree, and the board above the
|
||||
/// project became the board every write landed in.
|
||||
#[test]
|
||||
fn a_dangling_board_link_does_not_reach_the_board_above_it() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let above = project.parent().unwrap().join(".worklane");
|
||||
fs::create_dir_all(&above).unwrap();
|
||||
let link = project.join(".worklane");
|
||||
std::os::unix::fs::symlink(project.parent().unwrap().join("gone"), &link).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains(&link.display().to_string()), "{error}");
|
||||
|
||||
// And the walk really would have reached it, so the assertion above is
|
||||
// about where the walk stopped rather than about an empty tree.
|
||||
assert_eq!(find_worklane_dir(project.parent().unwrap()).unwrap(), above);
|
||||
}
|
||||
|
||||
/// Nothing at that path is still the one answer the walk carries on from.
|
||||
#[test]
|
||||
fn no_worklane_at_all_lets_the_walk_carry_on_upward() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let above = project.parent().unwrap().join(".worklane");
|
||||
fs::create_dir_all(&above).unwrap();
|
||||
|
||||
assert_eq!(find_worklane_dir(&project).unwrap(), above);
|
||||
}
|
||||
|
||||
/// A link that resolves is the board, and what comes back is the link rather
|
||||
/// than its target: `.worklane/backlog` has to read the same either way.
|
||||
#[test]
|
||||
fn a_link_to_a_board_resolves_the_way_a_directory_does() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let board = project.parent().unwrap().join("boards/2fed877-the-board");
|
||||
fs::create_dir_all(&board).unwrap();
|
||||
let link = project.join(".worklane");
|
||||
std::os::unix::fs::symlink(&board, &link).unwrap();
|
||||
|
||||
assert_eq!(find_worklane_dir(&project).unwrap(), link);
|
||||
}
|
||||
|
||||
/// A regular file is reported rather than stepped over, and a board above it
|
||||
/// does not make it the walk's problem to solve.
|
||||
#[test]
|
||||
fn a_regular_file_where_the_board_goes_is_an_error() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
fs::write(project.join(".worklane"), "board = \"2fed877\"\n").unwrap();
|
||||
fs::create_dir_all(project.parent().unwrap().join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains("not a directory"), "{error}");
|
||||
}
|
||||
|
||||
/// A link that resolves to a file, which the follow catches and the entry check
|
||||
/// on its own cannot: the entry is a symlink and the target is not a directory.
|
||||
#[test]
|
||||
fn a_link_to_a_file_is_not_a_board_either() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let file = project.parent().unwrap().join("pointer.toml");
|
||||
fs::write(&file, "board = \"2fed877\"\n").unwrap();
|
||||
std::os::unix::fs::symlink(&file, project.join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains("not a directory"), "{error}");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
|
||||
chmod(&backlog, 0o755);
|
||||
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
/// The board above the project is real and empty, and stays empty: a dangling
|
||||
/// `.worklane` link used to read as no board here, and the walk then wrote the
|
||||
/// ticket into whatever board sat above it.
|
||||
#[test]
|
||||
fn add_writes_nothing_when_the_board_link_does_not_resolve() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let above = setup_worklane(&temp);
|
||||
|
||||
let project = temp.child("project");
|
||||
project.create_dir_all().unwrap();
|
||||
let target = temp.path().join("boards/2fed877-the-board");
|
||||
std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd
|
||||
.current_dir(project.path())
|
||||
.args(["add", "--title", "Should not land"])
|
||||
.assert()
|
||||
.failure();
|
||||
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains(&target.display().to_string()), "{stderr}");
|
||||
assert!(stderr.contains("boards repo"), "{stderr}");
|
||||
|
||||
assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
@@ -13,6 +13,8 @@ const CAMP_B: &str = "bb22cc33-44dd-4ee5-8ff6-001122334455";
|
||||
const MEMBER: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
|
||||
const OTHER: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
|
||||
const LONER: &str = "f1f2f3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f";
|
||||
/// A second done member, for the one test that needs two in one column to see an order.
|
||||
const LATE: &str = "a9a8a7a6-5b4c-4d3e-8f2a-1b0c9d8e7f60";
|
||||
|
||||
fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
let worklane = temp.child(".worklane");
|
||||
@@ -507,6 +509,37 @@ fn campaign_show_prints_the_body_and_the_members_grouped_by_status() {
|
||||
assert!(!shown.contains("The loner"), "{shown}");
|
||||
}
|
||||
|
||||
/// The members of a status are listed in that status's own order, not in the board-wide
|
||||
/// one: a campaign's done list answers what just landed, for the same reason the board's
|
||||
/// column does. Every fixture is a p3, so the stamp is doing all of the work.
|
||||
#[test]
|
||||
fn campaign_show_lists_each_status_in_its_own_order() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let stamp = |uuid: &str, day: &str| {
|
||||
let path = find(&worklane, uuid);
|
||||
let body = fs::read_to_string(&path).unwrap().replace(
|
||||
"- **Status**: done\n",
|
||||
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
|
||||
);
|
||||
fs::write(&path, body).unwrap();
|
||||
};
|
||||
|
||||
// A second done member, finished after the one the fixture writes.
|
||||
create_ticket(&worklane, "done", "The late member", LATE);
|
||||
stamp(OTHER, "1");
|
||||
stamp(LATE, "3");
|
||||
|
||||
run(&temp, &["assign", "v1 release", OTHER]);
|
||||
run(&temp, &["assign", "v1 release", LATE]);
|
||||
|
||||
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
|
||||
let at = |needle: &str| shown.find(needle).unwrap_or_else(|| panic!("{needle}: {shown}"));
|
||||
|
||||
assert!(at("The late member") < at("The other member"), "{shown}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ls_campaign_lists_only_that_campaigns_members() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
/// The tool as this test's binary carries it, so the print path is pinned to the file in
|
||||
/// the repo rather than to a description of it.
|
||||
const TOOL: &str = include_str!("../assets/TOOL.ts");
|
||||
|
||||
/// `XDG_CONFIG_HOME` is redirected, and `HOME` with it, so the suite never writes into
|
||||
/// the config of whoever runs it. Both, because the fallback reads `HOME` and a machine
|
||||
/// that has neither set is not the case under test here.
|
||||
fn run(config: &TempDir, args: &[&str]) -> std::process::Output {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.env("XDG_CONFIG_HOME", config.path())
|
||||
.env("HOME", config.path())
|
||||
.args(args);
|
||||
cmd.assert().get_output().clone()
|
||||
}
|
||||
|
||||
fn installed(config: &TempDir) -> std::path::PathBuf {
|
||||
config.path().join("opencode/tool/worklane.ts")
|
||||
}
|
||||
|
||||
fn stdout(output: &std::process::Output) -> String {
|
||||
String::from_utf8(output.stdout.clone()).unwrap()
|
||||
}
|
||||
|
||||
/// Nothing about the tool needs a board, and it is wanted before there is one.
|
||||
///
|
||||
/// The file name is asserted, not just the directory: opencode names each tool as the
|
||||
/// file then the export, so `worklane.ts` is what makes them `worklane_add` and
|
||||
/// `worklane_mv`.
|
||||
#[test]
|
||||
fn the_tool_installs_outside_a_worklane_directory() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool"]);
|
||||
|
||||
assert!(output.status.success());
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains("Installed the worklane tool"),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// What the message has to carry, and it is not the skills' "next session": opencode
|
||||
/// reads its config once at startup and never reloads it, so a running one keeps the
|
||||
/// tools it began with. The second half is there because the file is executable and
|
||||
/// looks like it needs a toolchain, which it does not.
|
||||
#[test]
|
||||
fn the_tool_says_to_restart_opencode_and_that_nothing_else_is_needed() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Restart it"), "{out}");
|
||||
assert!(out.contains("never reloaded"), "{out}");
|
||||
assert!(out.contains("Nothing else to install"), "{out}");
|
||||
assert!(out.contains("Bun"), "{out}");
|
||||
}
|
||||
|
||||
/// Installing twice is a no-op rather than a rewrite, exactly as `install-skill` is.
|
||||
#[test]
|
||||
fn a_second_install_reports_the_copy_unchanged() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Already up to date"), "{out}");
|
||||
assert!(!out.contains("Installed the"), "{out}");
|
||||
}
|
||||
|
||||
/// An edited copy is somebody's work, and the refusal names the invocation that shows
|
||||
/// what it would be replaced with. `--print` there and not a skill name: there is one
|
||||
/// tool file, so nothing has to say which.
|
||||
#[test]
|
||||
fn a_modified_copy_is_refused_until_force() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
std::fs::write(installed(&config), "// hand written\n").unwrap();
|
||||
|
||||
let refused = stdout(&run(&config, &["install-tool"]));
|
||||
assert!(refused.contains("Differs from the version in this binary"), "{refused}");
|
||||
assert!(refused.contains("worklane install-tool --print"), "{refused}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), "// hand written\n");
|
||||
|
||||
let forced = stdout(&run(&config, &["install-tool", "--force"]));
|
||||
assert!(forced.contains("Installed the worklane tool"), "{forced}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
}
|
||||
|
||||
/// `--print` is for diffing against an installed copy, so it writes nothing.
|
||||
#[test]
|
||||
fn print_writes_the_tool_to_stdout_and_installs_nothing() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool", "--print"]);
|
||||
|
||||
assert_eq!(stdout(&output), TOOL);
|
||||
assert!(!installed(&config).exists());
|
||||
}
|
||||
|
||||
/// With no `XDG_CONFIG_HOME` the tool lands under `HOME`, which is the same answer
|
||||
/// opencode gives: its config root is `$XDG_CONFIG_HOME/opencode` when that is set and
|
||||
/// `~/.config/opencode` when it is not.
|
||||
#[test]
|
||||
fn the_tool_falls_back_to_the_home_directory_without_xdg_config_home() {
|
||||
let home = TempDir::new().unwrap();
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let output = cmd
|
||||
.env_remove("XDG_CONFIG_HOME")
|
||||
.env("HOME", home.path())
|
||||
.arg("install-tool")
|
||||
.assert()
|
||||
.success()
|
||||
.get_output()
|
||||
.clone();
|
||||
|
||||
let path = home.path().join(".config/opencode/tool/worklane.ts");
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains(&path.display().to_string()),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// The two commands are independent, which is the whole point of them being two: a
|
||||
/// person on Claude Code takes the skills and never the tool, and one who wants the
|
||||
/// tools is not made to take a second copy of the documents to get them.
|
||||
#[test]
|
||||
fn each_install_command_leaves_the_other_target_alone() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
|
||||
assert!(installed(&config).exists());
|
||||
assert!(!config.path().join(".claude/skills").exists());
|
||||
|
||||
let skills_only = TempDir::new().unwrap();
|
||||
run(&skills_only, &["install-skill"]);
|
||||
|
||||
assert!(
|
||||
skills_only
|
||||
.path()
|
||||
.join(".claude/skills/worklane/SKILL.md")
|
||||
.exists()
|
||||
);
|
||||
assert!(!installed(&skills_only).exists());
|
||||
}
|
||||
+199
-3
@@ -677,9 +677,9 @@ fn ls_names_the_four_statuses_when_given_another() {
|
||||
}
|
||||
}
|
||||
|
||||
/// The listing reads the fields it prints and nothing else, so the stamps `mv` writes
|
||||
/// do not reach it. Pinned against a ticket carrying one, since a listing that started
|
||||
/// showing them would change the output every board and completion script parses.
|
||||
/// The listing reads the stamps to order the column by them, and prints none of them.
|
||||
/// Pinned against a ticket carrying one, since a listing that started showing them would
|
||||
/// change the output every board and completion script parses.
|
||||
#[test]
|
||||
fn ls_output_is_unchanged_by_a_status_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -707,3 +707,199 @@ fn ls_output_is_unchanged_by_a_status_stamp() {
|
||||
assert_eq!(after, before);
|
||||
assert!(!after.contains("Committed On"), "{after}");
|
||||
}
|
||||
|
||||
/// A ticket in a status with the entry stamp that status is ordered by, or none.
|
||||
///
|
||||
/// The field is derived from the status rather than passed, so a case says which column
|
||||
/// it is about and cannot name the wrong stamp for it.
|
||||
fn create_stamped_ticket(
|
||||
worklane_dir: &std::path::Path,
|
||||
status: &str,
|
||||
title: &str,
|
||||
uuid: &str,
|
||||
priority: &str,
|
||||
stamp: Option<&str>,
|
||||
) {
|
||||
let field = match status {
|
||||
"committed" => "Committed On",
|
||||
"reviewing" => "Submitted On",
|
||||
"done" => "Completed On",
|
||||
other => panic!("{other} has no entry stamp"),
|
||||
};
|
||||
let line = match stamp {
|
||||
Some(value) => format!("- **{field}**: {value}\n"),
|
||||
None => String::new(),
|
||||
};
|
||||
let body = format!(
|
||||
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Priority**: {priority}\n\
|
||||
- **Tags**: test\n- **Due**: _Not set_\n- **Owner**: alice\n{line}\
|
||||
- **Status**: {status}\n"
|
||||
);
|
||||
fs::write(
|
||||
worklane_dir
|
||||
.join(status)
|
||||
.join(format!("{uuid}_{}.md", slug(title))),
|
||||
body,
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
fn positions(stdout: &str, titles: [&str; 3]) -> Vec<usize> {
|
||||
titles
|
||||
.iter()
|
||||
.map(|title| {
|
||||
stdout
|
||||
.find(title)
|
||||
.unwrap_or_else(|| panic!("{title} missing from {stdout}"))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Committed and reviewing are queues, and the head is what has waited longest: that is
|
||||
/// what the reader picks next from. Priority no longer decides it, which is why the
|
||||
/// oldest here is the least urgent of the three.
|
||||
#[test]
|
||||
fn ls_orders_committed_and_reviewing_by_the_oldest_entry_stamp() {
|
||||
for status in ["committed", "reviewing"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("aaaa000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Middle",
|
||||
&at(3),
|
||||
"1",
|
||||
Some("2026-08-02 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", status]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status}: {stdout}");
|
||||
|
||||
// The overview lists the same columns, 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, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status} overview: {overview}");
|
||||
}
|
||||
}
|
||||
|
||||
/// Done reads like a changelog: what just landed is at the top. The p1 that finished
|
||||
/// first is at the bottom, which is the whole point of the column not being priority.
|
||||
#[test]
|
||||
fn ls_orders_done_by_the_newest_entry_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("bbbb000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "done", "First", &at(1), "1", Some("2026-08-01 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Last", &at(2), "5", Some("2026-08-03 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Middle", &at(3), "1", Some("2026-08-02 09:00:00"));
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "done"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Last", "Middle", "First"]);
|
||||
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.
|
||||
#[test]
|
||||
fn ls_sinks_an_unstamped_ticket_below_the_stamped_ones() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("cccc000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "committed", "Unstamped", &at(1), "1", None);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Waited",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Fresh",
|
||||
&at(3),
|
||||
"5",
|
||||
Some("2026-08-09 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "committed"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Waited", "Fresh", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// The two listings are one order. A completion offering candidates in a different
|
||||
/// order than the board prints them would make the head of a column mean two things.
|
||||
#[test]
|
||||
fn ls_ids_prints_the_same_order_the_listing_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("dddd000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(&worklane, "reviewing", "Unstamped", &at(3), "1", None);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing", "--ids"]);
|
||||
let ids = get_stdout(&mut cmd);
|
||||
|
||||
let titles: Vec<&str> = ids.lines().filter_map(|line| line.split('\t').nth(1)).collect();
|
||||
assert_eq!(titles, ["Oldest", "Newest", "Unstamped"], "{ids:?}");
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
+103
-13
@@ -923,35 +923,89 @@ fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
|
||||
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
|
||||
}
|
||||
|
||||
/// One field per status, written with the time of the move, and only the current one:
|
||||
/// the stamps are where the ticket is now, not the trail of how it got there.
|
||||
/// One field per status, written with the time of the move and added to the ones
|
||||
/// already there: walking the flow leaves the whole journey on the ticket.
|
||||
#[test]
|
||||
fn mv_stamps_the_field_of_the_status_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
for (status, stamp, cleared) in [
|
||||
("committed", "Committed On", "Submitted On"),
|
||||
("reviewing", "Submitted On", "Committed On"),
|
||||
("done", "Completed On", "Submitted On"),
|
||||
// The fixture predates Created At as well as the stamps, and the four reading as
|
||||
// one block is the point, so it is seeded rather than asserted around.
|
||||
let path = worklane.join("backlog").join(&filename);
|
||||
let seeded = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:");
|
||||
fs::write(&path, seeded).unwrap();
|
||||
|
||||
let mut carried: Vec<&str> = Vec::new();
|
||||
|
||||
for (status, stamp) in [
|
||||
("committed", "Committed On"),
|
||||
("reviewing", "Submitted On"),
|
||||
("done", "Completed On"),
|
||||
] {
|
||||
let out = move_ticket(&temp, "cccc3333", status, false);
|
||||
assert!(out.status.success(), "{:?}", out);
|
||||
carried.push(stamp);
|
||||
|
||||
let content = ticket_at(&worklane, status, &filename);
|
||||
let value = field(&content, stamp)
|
||||
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
|
||||
|
||||
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
|
||||
assert_eq!(field(&content, cleared), None, "{content}");
|
||||
for stamp in &carried {
|
||||
let value = field(&content, stamp)
|
||||
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
|
||||
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
|
||||
}
|
||||
}
|
||||
|
||||
// The four side by side and in flow order, which is what a reader asking when this
|
||||
// was filed, picked up, handed over and finished gets one answer each from.
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
let block: Vec<&str> = content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("- **"))
|
||||
.filter_map(|line| line.split("**:").next())
|
||||
.skip_while(|name| *name != "Created At")
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
block,
|
||||
[
|
||||
"Created At",
|
||||
"Committed On",
|
||||
"Submitted On",
|
||||
"Completed On",
|
||||
"Status"
|
||||
],
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all
|
||||
/// rather than a Completed On for work that has been undone.
|
||||
/// Arrival clears what comes after it and nothing before, so a ticket sent back out of
|
||||
/// done keeps the stages it did get through.
|
||||
#[test]
|
||||
fn mv_removes_the_stamp_of_the_status_it_leaves() {
|
||||
fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
for status in ["committed", "reviewing", "done"] {
|
||||
move_ticket(&temp, "cccc3333", status, false);
|
||||
}
|
||||
|
||||
move_ticket(&temp, "cccc3333", "reviewing", true);
|
||||
|
||||
let content = ticket_at(&worklane, "reviewing", &filename);
|
||||
assert_eq!(field(&content, "Completed On"), None, "{content}");
|
||||
assert!(field(&content, "Committed On").is_some(), "{content}");
|
||||
assert!(field(&content, "Submitted On").is_some(), "{content}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own and every status follows it, so a ticket forced back
|
||||
/// to it carries none at all rather than a Completed On for work that has been undone.
|
||||
#[test]
|
||||
fn mv_back_to_backlog_removes_all_three_stamps() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
@@ -968,6 +1022,42 @@ fn mv_removes_the_stamp_of_the_status_it_leaves() {
|
||||
}
|
||||
}
|
||||
|
||||
/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent
|
||||
/// field says the ticket never got that far, and inventing one would say it did.
|
||||
#[test]
|
||||
fn mv_skipping_forward_stamps_only_the_target() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "done", true);
|
||||
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
assert!(field(&content, "Completed On").is_some(), "{content}");
|
||||
assert_eq!(field(&content, "Committed On"), None, "{content}");
|
||||
assert_eq!(field(&content, "Submitted On"), None, "{content}");
|
||||
}
|
||||
|
||||
/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to
|
||||
/// write one or take one away, so a stamp is always the record of a real move. Pinned
|
||||
/// so the omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
#[test]
|
||||
fn no_other_command_can_write_or_clear_a_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
for command in ["add", "set", "append", "chown"] {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args([command, "--help"]);
|
||||
let out = cmd.assert().get_output().clone();
|
||||
let help = String::from_utf8_lossy(&out.stdout).to_lowercase();
|
||||
|
||||
for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] {
|
||||
assert!(!help.contains(flag), "{command} --help names {flag}: {help}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Re-entry is the time of the move that brought the ticket back, not the first one.
|
||||
#[test]
|
||||
fn mv_restamps_a_status_the_ticket_is_re_entering() {
|
||||
|
||||
@@ -4,6 +4,11 @@
|
||||
//! tags exist, which is the question a grooming sweep starts from. So the properties
|
||||
//! under test are the ones that question needs: every status counted, case kept apart,
|
||||
//! alphabetical order, and an output a shell can parse.
|
||||
//!
|
||||
//! `tags add` is the other half of the same question. The listing reports the vocabulary
|
||||
//! the tickets *carry*; the file reports the one the board *intends*, and the tests below
|
||||
//! are mostly about the two being allowed to disagree without either one damaging the
|
||||
//! other.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
@@ -175,3 +180,357 @@ fn tags_skips_a_missing_status_directory() {
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------- the vocabulary --
|
||||
|
||||
fn vocabulary(temp: &TempDir) -> String {
|
||||
fs::read_to_string(temp.path().join(".worklane").join("tags.md")).unwrap()
|
||||
}
|
||||
|
||||
/// The section a tag holds in the file, heading excluded, or `None` when it is not
|
||||
/// declared. Cut out of the file rather than asserted against a whole rendering, so a
|
||||
/// change to the preamble does not fail every test here.
|
||||
fn declared(temp: &TempDir, tag: &str) -> Option<String> {
|
||||
let file = vocabulary(temp);
|
||||
let (_, rest) = file.split_once(&format!("\n## {tag}\n"))?;
|
||||
let body = match rest.split_once("\n## ") {
|
||||
Some((body, _)) => body,
|
||||
None => rest,
|
||||
};
|
||||
|
||||
Some(body.trim().to_string())
|
||||
}
|
||||
|
||||
/// The declaration lands in the file, with the annotation under it.
|
||||
#[test]
|
||||
fn tags_add_declares_a_tag_with_what_it_means() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"--annotation",
|
||||
"Something the binary does wrong.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something the binary does wrong."));
|
||||
}
|
||||
|
||||
/// Several flags are several lines, and an empty one is a paragraph break, the way a
|
||||
/// description is written.
|
||||
#[test]
|
||||
fn an_annotation_takes_several_lines_and_a_paragraph_break() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"add",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
|
||||
}
|
||||
|
||||
/// A tag can be declared with nothing said about it. The word being agreed on is worth
|
||||
/// recording before anyone has written the sentence.
|
||||
#[test]
|
||||
fn a_tag_can_be_declared_without_an_annotation() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags", "add", "cli"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
assert_eq!(declared(&temp, "cli").as_deref(), Some("_No annotation provided._"));
|
||||
}
|
||||
|
||||
/// Refused rather than overwritten, and the refusal names what does overwrite it: an
|
||||
/// annotation is the sentence a team files tickets against, not something to replace by
|
||||
/// typing `add` twice.
|
||||
#[test]
|
||||
fn declaring_a_tag_twice_is_refused_and_names_the_command_that_replaces_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
|
||||
let out = run(&temp, &["tags", "add", "bug", "-a", "A different sentence."]);
|
||||
|
||||
assert!(!out.status.success());
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("tags set"), "{stderr}");
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The first sentence."));
|
||||
}
|
||||
|
||||
/// A comma is what separates one tag from the next, so a value carrying one could never be
|
||||
/// matched by `--tag`. Refused at parse, with nothing written.
|
||||
#[test]
|
||||
fn a_tag_the_filter_could_never_match_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
for value in ["bug,cli", ""] {
|
||||
let out = run(&temp, &["tags", "add", value]);
|
||||
assert!(!out.status.success(), "'{value}' was accepted");
|
||||
}
|
||||
|
||||
// Nothing was written on the way past, not even the empty file.
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
}
|
||||
|
||||
/// Surrounding space is trimmed rather than refused, because a ticket's Tags field is read
|
||||
/// that way too: ` bug ` on a card is the tag `bug`, and the vocabulary has to agree.
|
||||
#[test]
|
||||
fn a_padded_tag_is_declared_under_its_trimmed_name() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", " bug "]);
|
||||
assert!(declared(&temp, "bug").is_some(), "{}", vocabulary(&temp));
|
||||
}
|
||||
|
||||
/// An annotation line that would be read back as a heading is refused, since it would split
|
||||
/// the section and declare whatever followed it.
|
||||
#[test]
|
||||
fn an_annotation_that_would_read_as_a_heading_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags", "add", "bug", "-a", "## cli"]);
|
||||
assert!(!out.status.success());
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
}
|
||||
|
||||
/// The file is made on demand, the way `campaign add` makes the campaigns directory: a board
|
||||
/// that predates the vocabulary must not need `worklane init` run over it.
|
||||
#[test]
|
||||
fn the_file_is_created_on_a_board_that_predates_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
assert!(declared(&temp, "bug").is_some());
|
||||
}
|
||||
|
||||
/// `init` writes it, so a new board has one file shape rather than two.
|
||||
#[test]
|
||||
fn init_writes_the_vocabulary_beside_the_status_directories() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let out = run(&temp, &["init"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
let file = vocabulary(&temp);
|
||||
assert!(file.starts_with("# Tags"), "{file}");
|
||||
// The preamble and nothing else: a new board declares no tags.
|
||||
assert!(!file.contains("\n## "), "{file}");
|
||||
}
|
||||
|
||||
/// A second declaration keeps the first, and the file stays alphabetical: the whole file is
|
||||
/// re-rendered, so this is the test that the re-render is not a truncation.
|
||||
#[test]
|
||||
fn declaring_a_tag_leaves_the_others_alone_and_keeps_the_order() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["tags", "add", "tui", "-a", "The board view."]);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "Something wrong."]);
|
||||
|
||||
assert_eq!(declared(&temp, "tui").as_deref(), Some("The board view."));
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Something wrong."));
|
||||
|
||||
let file = vocabulary(&temp);
|
||||
assert!(file.find("## bug").unwrap() < file.find("## tui").unwrap(), "{file}");
|
||||
}
|
||||
|
||||
/// A file that is there and cannot be read stops the write rather than being taken for an
|
||||
/// empty vocabulary. Empty would mean erased, since every declaration re-renders the file.
|
||||
#[test]
|
||||
fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
// A directory where the file should be: `read_to_string` fails on it, which a missing
|
||||
// file does not.
|
||||
fs::create_dir(worklane.join("tags.md")).unwrap();
|
||||
|
||||
let out = run(&temp, &["tags", "add", "bug"]);
|
||||
assert!(!out.status.success());
|
||||
assert!(worklane.join("tags.md").is_dir(), "the file was replaced");
|
||||
|
||||
// And nothing was staged and left behind.
|
||||
let stray: Vec<_> = fs::read_dir(&worklane)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.filter(|e| e.file_name().to_string_lossy().starts_with(".wl-"))
|
||||
.collect();
|
||||
assert!(stray.is_empty(), "a temp file was left in .worklane");
|
||||
}
|
||||
|
||||
/// The vocabulary does not touch the listing, which counts tickets. The two disagreeing is
|
||||
/// the normal state and the thing the file is for.
|
||||
#[test]
|
||||
fn a_declared_tag_is_not_a_carried_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
run(&temp, &["tags", "add", "chore", "-a", "Housekeeping."]);
|
||||
|
||||
// `chore` is declared and carried by nothing, `bug` is carried and declared by nothing,
|
||||
// and the listing still answers only the second question. Reporting both is 9564ac9.
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
|
||||
/// that way to fill in `ls --tag`. `tags ls` is the same thing spelled as a group.
|
||||
#[test]
|
||||
fn the_bare_form_and_ls_are_the_same_listing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
run(&temp, &["tags", "add", "chore"]);
|
||||
|
||||
let bare = run(&temp, &["tags"]);
|
||||
let group = run(&temp, &["tags", "ls"]);
|
||||
|
||||
assert!(bare.status.success());
|
||||
assert_eq!(bare.stdout, group.stdout);
|
||||
assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n");
|
||||
}
|
||||
|
||||
// -------------------------------------------------- changing what a tag means --
|
||||
|
||||
/// The replacement lands, and replaces rather than appends.
|
||||
#[test]
|
||||
fn tags_set_replaces_what_a_tag_means() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The first sentence."]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug", "-a", "The second sentence."]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The second sentence."));
|
||||
assert!(!vocabulary(&temp).contains("first"), "the old annotation survived");
|
||||
}
|
||||
|
||||
/// Paragraph breaks survive the round trip, which is the whole difference between an
|
||||
/// annotation and a one-line description of a tag.
|
||||
#[test]
|
||||
fn a_multiline_annotation_survives_being_set() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"tags",
|
||||
"set",
|
||||
"bug",
|
||||
"-a",
|
||||
"What it is.",
|
||||
"-a",
|
||||
"",
|
||||
"-a",
|
||||
"When to use it.",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("What it is.\n\nWhen to use it."));
|
||||
}
|
||||
|
||||
/// Set to what it already says, nothing is written and the command says so, the way `set`
|
||||
/// and `chown` report a field that already holds the value.
|
||||
#[test]
|
||||
fn setting_an_annotation_to_what_it_already_says_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
let before = fs::metadata(temp.path().join(".worklane").join("tags.md"))
|
||||
.unwrap()
|
||||
.modified()
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug", "-a", "The sentence."]);
|
||||
assert!(out.status.success());
|
||||
assert!(String::from_utf8_lossy(&out.stdout).contains("No changes"), "{out:?}");
|
||||
|
||||
let after = fs::metadata(temp.path().join(".worklane").join("tags.md"))
|
||||
.unwrap()
|
||||
.modified()
|
||||
.unwrap();
|
||||
assert_eq!(before, after, "the file was rewritten for a no-op");
|
||||
}
|
||||
|
||||
/// `add` and `set` are a pair, each refusing what the other is for, so the refusal names
|
||||
/// the other command rather than leaving it to be found.
|
||||
#[test]
|
||||
fn setting_a_tag_that_is_not_declared_is_refused_and_names_add() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug"]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "cli", "-a", "Anything."]);
|
||||
|
||||
assert!(!out.status.success());
|
||||
let stderr = String::from_utf8_lossy(&out.stderr);
|
||||
assert!(stderr.contains("tags add"), "{stderr}");
|
||||
assert!(declared(&temp, "cli").is_none(), "the tag was declared by set");
|
||||
}
|
||||
|
||||
/// A bare `tags set <tag>` is a usage error. Nothing to write is a mistake in the call, not
|
||||
/// a command that quietly does nothing.
|
||||
#[test]
|
||||
fn setting_nothing_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
let out = run(&temp, &["tags", "set", "bug"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{out:?}");
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("The sentence."));
|
||||
}
|
||||
|
||||
/// An annotation can be emptied back to the placeholder, which is the state a tag declared
|
||||
/// without one is already in. That is why there is no `--clear`.
|
||||
#[test]
|
||||
fn an_annotation_can_be_emptied_back_to_the_placeholder() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "The sentence."]);
|
||||
|
||||
run(&temp, &["tags", "set", "bug", "-a", ""]);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("_No annotation provided._"));
|
||||
}
|
||||
|
||||
/// The other tags keep their sections, since the whole file is re-rendered on every write.
|
||||
#[test]
|
||||
fn setting_one_annotation_leaves_the_others_alone() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
run(&temp, &["tags", "add", "bug", "-a", "About bugs."]);
|
||||
run(&temp, &["tags", "add", "tui", "-a", "About the board."]);
|
||||
|
||||
run(&temp, &["tags", "set", "bug", "-a", "Rewritten."]);
|
||||
|
||||
assert_eq!(declared(&temp, "bug").as_deref(), Some("Rewritten."));
|
||||
assert_eq!(declared(&temp, "tui").as_deref(), Some("About the board."));
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user