Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
9d17f55860 | ||
|
|
f454d212a4 | ||
|
|
a1bdb5df49 | ||
|
|
c2ee165108 | ||
|
|
407cb14fe6 | ||
|
|
108e21ad7f | ||
|
|
26b93f8f53 | ||
|
|
7126138d46 | ||
|
|
3592584747 | ||
|
|
5dc087d49e | ||
|
|
07c783410c | ||
|
|
dd2b457bff | ||
|
|
af1ef1f97f | ||
|
|
8e2ab6332c | ||
|
|
239d951b8c |
@@ -7,28 +7,31 @@
|
||||
- `src/handlers.rs` - one `cmd_*` per subcommand
|
||||
- `src/util.rs` - the ticket format, resolution, rendering and the palette
|
||||
- `src/campaign.rs` - the campaign file format, its resolution, its index and its members
|
||||
- `src/history.rs` - the history log: the path, the kinds, the reader, the writer, the card's counter and the block `show` and the board both render
|
||||
- `src/tui.rs` - board state, the change digest, and the ratatui draw
|
||||
- `src/clipboard.rs` - the OSC 52 write and the base64 it carries, the board's only way out to the clipboard
|
||||
- `src/install.rs` - the embedded agent assets and the compare-and-refuse install
|
||||
- `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/ADMIN.md` - the agent skill for the board itself: designing and annotating the tag vocabulary, and repairing a board whose files and fields have come apart. The one asset written to hold for a board that tracks no software, so its examples span three subjects on purpose. It draws the line against `PLAN.md` in both directions: this one decides the vocabulary, that one applies it
|
||||
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
|
||||
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `history.rs` and `tui.rs`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
- History entries stored as `.md` in `.worklane/history/<ticket_uuid>/`, one file per entry, beside the status directories for the reason campaigns are
|
||||
- Campaign files stored as `.md` in `.worklane/campaigns/`, which is beside the status directories and deliberately not in `status_dirs()`
|
||||
|
||||
## Ticket File Format
|
||||
- Filenames: `<uuid_v4>_<slug>.md`
|
||||
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
|
||||
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Not the history log either: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
|
||||
- Format: `**Field Name**: value`
|
||||
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
|
||||
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
|
||||
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
|
||||
- History entries stored in `.worklane/history/<ticket_uuid>/<stamp>_<kind>.md`, with the kind's marker (`**Comment**`, `**Status**`, `**Owner**`, `**Tags**`), then the body, then `**Author**` and `**Time**`. See The History Log
|
||||
|
||||
## Status Workflow
|
||||
`backlog` → `committed` → `reviewing` → `done`
|
||||
@@ -44,6 +47,10 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Tests use `assert_cmd` and `assert_fs` for CLI testing
|
||||
- `setup_worklane()` creates temp `.worklane/` with all four status folders pre-created, plus `campaigns/` in `cmd_campaign.rs`, which is also where the on-demand creation is tested from a board without it
|
||||
- `create_ticket()` writes fully-formed markdown files directly (no `--` separator for positional args in test commands)
|
||||
- **Every unit-test fixture directory goes through `util::Fixture`, and nothing calls `remove_dir_all` at the end of a test.** `Fixture::new(prefix)` makes a uuid-named directory under the system temp dir and its `Drop` removes it, which is the only shape that also runs when an assertion fails — a trailing line does not, and a failing test is exactly when a fixture is most likely to be stranded. That was b74dc5a: `/tmp` reached 18363 of these and filled the disk, failing a link step and then a `git add` with "No space left on device", an error naming neither the tests nor what they left behind
|
||||
- **`Fixture` derefs to `Path` and also implements `AsRef<Path>`**, because the two reach different call sites: a parameter typed `&Path` is a coercion site and one bound by `impl AsRef<Path>` is not. `Fixture::child(name)` points the fixture at a directory inside itself while still removing the parent, which is the tree `project_tree` needs. The prefix earns its place on the one path that is ever left behind, which is why this is a small guard rather than `assert_fs::TempDir` — that names its directories `.tmpXXXXXX`, which says nothing about whose they are
|
||||
- **`WORKLANE_KEEP_FIXTURES=1 cargo test` keeps the fixtures and prints each path.** Opt-in rather than kept-automatically-on-failure, because the assertions here carry the state they are about: a failing board test prints the rendered rows. The flag is read once when a fixture is made rather than at drop time, so the answer cannot change mid-test, and `Fixture::swept()` turns it off for the three tests that are about the guard itself and must not be failed by a reader's environment
|
||||
- **Verify a claim about leaked fixtures against a clean temp dir, not against `/tmp`.** `TMPDIR=/tmp/scratch cargo test` then count what is left in it: `/tmp` still holds the historical leak, so counting there measures the past rather than the change
|
||||
- In `tui.rs`, `write_member_card` is `write_tagged_card` plus a Campaign field and `write_campaign` puts a campaign on disk, creating the campaigns directory as it goes — `board_dir()` deliberately does not, so every test that does not write one is also the test that a board with no campaigns draws. `picker_rows` cuts the picker's list out of the frame by its own geometry, for the reason `overlay_title_row` exists: a card carries the same campaign label, so a search over every row finds the board rather than the list
|
||||
- **`cargo clippy --all-targets` is clean. Keep it clean**, and do not silence a lint that is pointing at something real. The only two `allow`s in the tree sit on the `create_ticket` fixtures in `cmd_mv.rs` and `cmd_show.rs`, each carrying the reason and what would replace it
|
||||
- **`cargo fmt --check` is clean too, and `rustfmt.toml` is what makes that affordable.** rustfmt is the formatter here, run it. The config is four stable width settings and nothing else:
|
||||
@@ -120,6 +127,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written
|
||||
- Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description
|
||||
- An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does
|
||||
- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear <field>` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two
|
||||
|
||||
### Clearing a Field
|
||||
- **`set --clear <field>` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes
|
||||
@@ -169,7 +177,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A campaign's state is derived, never stored.** Open until every member is done, computed by `Standing` from the members. A `Status` field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no `campaign mv` and no forward-only ruleset beside `mv`'s
|
||||
- **A campaign with no members is neither open nor done.** `Standing::state()` returns `None` there, and both callers print `no members`. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
|
||||
- **Membership is one field on the member**, `Campaign` in the ticket Metadata, written only by `assign`. The member list is deliberately *not* on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So `add` has no `--campaign` and `set` has no `--campaign`, the same rule as Owner and Status
|
||||
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cell` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
|
||||
- **The full uuid is stored and the title is resolved for display**, as the Relations section already does. `reference_cells` is shared between the two, so a dangling campaign and a dangling relation target are both spelled `_missing_` rather than each inventing a spelling
|
||||
- **`add` does not write the field.** Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of `add` means one path that is always exercised rather than two. Same reasoning as the Relations section
|
||||
- `set_or_insert_metadata_field()` is the upsert, and `METADATA_ORDER` is its anchor list, the way `SECTION_ORDER` is `ensure_section`'s. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no `## Metadata` heading is an **error, not an insertion**: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
|
||||
- **The four tiers are `resolve_in()`, shared by tickets and campaigns.** A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. `Found.dir` is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
|
||||
@@ -180,9 +188,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
|
||||
- **The TUI got a card label and a frame, not a campaign tab.** 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups *across* the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and `c` for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in `columns_of` and is what names the label; see The Board View
|
||||
- **A campaign is named by its codename on the board, and by its short id when it has none.** The uuid does not fit on a card and the title is a sentence, which is the gap `Codename` fills. `campaign_label` builds it in one place, as a `Cell`, so the CLI paints it and the board makes a span of it; the mark is `CAMPAIGN_MARK`, `~`, beside `#` for a tag
|
||||
- **`campaign set` is the only writer of a filed campaign's fields, and it carries the two scalars.** d637288 decided it: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `--title`, which renames the file the way `set --title` does, and `--codename`. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **`campaign set` and `campaign append` are the only writers of a filed campaign's fields.** d637288 decided the command: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `set` carries `--title`, which renames the file the way `set --title` does, `--description` and `--codename`; `append` carries `--description` alone. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist
|
||||
- **Replacing a codename the campaign already has needs `--force`.** Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake `install-skill --force` exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field. Setting the codename a campaign already carries stays a **no-op, not a refusal** — `--force` is about overwriting a *different* word, which is the same division `install::Outcome` draws between `Unchanged` and `Refused`. `--force` guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
|
||||
- **No `campaign set --description`, and that is the line, not an oversight.** `set` and `append` are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line `append` already draws for a ticket. `campaign_set_offers_no_description_and_no_owner` pins it. No `--owner` either, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign; and no `--clear`, because a wrong codename is replaced rather than emptied and `Clearable` is `SetArgs`'s, its variants being a ticket's fields
|
||||
- **The description arrived as a pair, `set --description` and `campaign append`, 32e98ab.** Never one without the other: for a prose section `set` replaces and `append` adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line `append` already draws for a ticket, and `campaign_append_offers_only_the_description` pins that. Neither flag takes `--force`: a description is prose written to be revised, the same reason `tags set --annotation` has none
|
||||
- **`append` is a campaign's own subcommand, not the top-level `append`.** That one resolves a ticket, and one positional naming either object is the ambiguity `resolve_in` makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of `resolve_ticket`, which explains a ticket search that *names* a campaign. Under `campaign` the object is settled by the command, as it is for `set`, `show` and `ls`
|
||||
- **Still no `--owner` and still no `--clear`.** No `--owner`, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign. No `--clear`, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be `Clearable` on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. `campaign_set_offers_no_owner_and_no_clear` pins both
|
||||
- **An empty `--description ""` is a paragraph break here too, and the refusal for an all-blank value names no flag.** Every prose argument in the tool reads a blank value that way, `add`, `set` and `tags --annotation` alike, so a campaign reading it as *empty the section* would be the one exception. With no `--clear` to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. `replaced_items` is where the check lives, shared with `set`, and the way out is the caller's argument for exactly that reason
|
||||
- **`SECTION_ORDER` needs no campaign variant, and that is what the one-section file proves.** A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, *filtered by what is actually in the file*, so a campaign's description anchors against `## Metadata` — which is where `campaign_body` writes it. `the_description_is_edited_in_place_in_a_file_with_one_section` pins that no section a campaign does not have gets inserted to anchor against
|
||||
- **A campaign whose Description heading is gone is refused, not given the section back.** No `ensure_section` on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where `add` writes nothing and the insertion is the only path there is. The refusal therefore names the section and **not** the object — "There is no description section to write to" — because both a ticket and a campaign reach `replace_section_body` now. `write_then_replace` still carries the noun, where the message is about a file
|
||||
- **The codename is written through `set_or_insert_metadata_field`, not `set_metadata_field`.** Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts `assign` on the upsert. **`Codename` is therefore in `METADATA_ORDER`, directly after ID**, so an inserted one lands where `campaign_body` writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
|
||||
- **One write path for tickets and campaigns.** `save_entry` is the body, `save_ticket` and `save_campaign` are the named wrappers, and `write_then_replace` and `find_entry_file` take the noun as a `&str` so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, `<uuid>_<slug>.md` in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
|
||||
- `campaign_body()` builds the file from `DESCRIPTION` and `METADATA_HEADING` rather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status
|
||||
@@ -198,6 +211,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `notify` is deliberately not a dependency. Polling a tree of tens of small files on the 250ms tick is enough, and the reason is recorded on f6af387
|
||||
- Cards come from `collect_ticket_items`, the same source `ls` uses, so there is no second parser. `TicketItem::path` exists for the detail view
|
||||
- **The detail view scrolls on `pgup` and `pgdn`, not on up and down.** Up and down stay on the selection with the modal open, so a whole column can be read without closing it, and the modal follows. That is worth more than the two keys, which is why the scroll went elsewhere rather than taking them
|
||||
- **The campaign frame scrolls on the same two keys, and `Board::scroll_page` is where the precedence lives.** An open ticket wins, whatever holds the selection behind it; the frame takes them only when there is no overlay to take them first. In `Board` rather than in the `main.rs` arm for the reason `dismiss` is: a layering rule written into that dispatch is a rule nothing can check
|
||||
- The scroll offset is clamped against the *wrapped* line count, from `Paragraph::line_count`, which is why `ratatui` carries the `unstable-rendered-line-info` feature. The paragraph wraps on words, so a clamp on the raw lines would stop short of the end or scroll past it into blank space. Counting the wrapping by hand would only agree with the widget until one of the two changed
|
||||
- The clamp runs on the keypress and again in the draw. The terminal can be resized between the two, and a tick can shorten the ticket under a reader who is already at the end
|
||||
- The offset resets when the selection moves and when the modal is closed, so a ticket opens at its top. It deliberately does *not* reset on a tick: an edit elsewhere in the tree must not throw the reader back to the top of what they are reading
|
||||
@@ -217,7 +231,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The footer's last slot always answers how to get out**, and with a ticket open the honest answer is `ctrl-c`, the only key left that quits in one press. Going on saying `q quit` there would be 1b78a24 in the other direction: a footer describing a key by what it used to do
|
||||
- **The overlay names its ticket on the border, not at the head of the paragraph.** `Board::detail` is a `Detail` carrying the title, the id and the text, because the name has to travel beside the body rather than inside it: `content_trim` drops the `# ` heading on purpose, since `cmd_show` prints it, and anything in the paragraph scrolls away
|
||||
- `detail_title` cuts the string itself instead of leaving it to ratatui, which truncates an overlong block title at whatever cell it reaches and would take the id with it. Cut against the inner width, so the id survives whole and the name ends in an ellipsis. The id goes first because that is how every other view addresses a ticket
|
||||
- The detail view renders with colour off. ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_comments_with` take the colour decision for that reason
|
||||
- The detail view renders from cells, never from painted strings: ratatui draws styled spans, so an escape sequence in a paragraph would be printed as literal bytes. `content_trim` and `format_history_with` take the colour decision for the CLI's side of the same layouts
|
||||
- Read only. Moving a card by keypress is a follow-up, deliberately kept out until the watch and render loop were solid
|
||||
- **A card is four corners with the title between them:** mark and short id top left, due top right, owner bottom left, comment count then criteria count bottom right. The numbers are in corners because that is where the eye goes for one, and they were invisible at the end of a line of prose
|
||||
- The title takes one row or two, wrapped on spaces, with an ellipsis when even two are not enough. One row when one is enough: a second, blank row on every short ticket spends the column's height on nothing
|
||||
@@ -225,19 +239,31 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
|
||||
- **`corner_line`'s right side is a group, single-spaced, and it gives up its items from the front.** The item nearest the edge is what the corner is *about*; anything to its left has been added beside it. So the bottom row loses its comment count before its criteria count, and the top row, with one item, behaves exactly as it did when the parameter was an `Option`. The spacing between the items lives in `corner_line` with the gap arithmetic rather than in a caller, for the reason `column_areas` is shared: geometry reproduced by hand drifts from the draw. `due_span` returns a `Span` and not an `Option<Span>` now, since the `Option` only ever existed to satisfy the old signature and the function cannot fail
|
||||
- The criteria count is a field on `TicketItem`, filled in `collect_ticket_items` where the file is already being read, and counted through `criteria()` so a checkbox in a description is not counted here or numbered by `show`. Do not count per card: that re-reads every ticket body on every draw instead of on the tick that changed something. `None` rather than `[0/0]` for a ticket with no criteria
|
||||
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The comments live outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_comments` applies, and no body is read, because a count needs none of them. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the comments of another. `comments_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
|
||||
- **The comment count is the same field discipline and the one entry on that pass that costs a directory listing.** The history lives outside the ticket file, so `count_comments` is a `read_dir` rather than a parse: `.md` only, the filter `read_history` applies, and no body is read, because a count needs none of them. **It counts comments and not entries**, off the kind in the filename, so a card still says how many things somebody said: a ticket that has moved three times has not been talked about, and counting the moves would put a number on every card on the board. `collect_ticket_items` derives the board from `status_path.parent()` instead of taking it as a second argument, so a status directory from one board cannot arrive with the history of another. `history_dir` spells the path once for the writer, the reader and the counter, the way `campaigns_dir` does. Zero draws nothing, not a `0` and not a blank: an uncommented card is the row it has always been, which `a_card_with_no_comments_spends_nothing_on_the_corner` pins to the exact spacing
|
||||
- **The count is cyan and the mark is `COMMENT_MARK`, U+275E, a Dingbat.** It is the only coloured thing on a row whose owner and criteria count are grey, because two counts side by side otherwise read as one number in brackets and another that lost its brackets. Not U+1F4AC SPEECH BALLOON: emoji presentation and East Asian Width Wide, so it draws two cells where `spans_width` counts one character and every corner on the card lands a cell out. Not U+1F5E8 LEFT SPEECH BUBBLE either: text presentation and Neutral, but in a pictograph block most terminal fonts leave as tofu. Check both properties before swapping the glyph
|
||||
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the comments directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
|
||||
- **`the_count_is_read_when_the_items_are_collected_and_not_per_draw` takes the history directory away after the board is built**, and is paired with `a_comment_added_after_the_board_was_built_reaches_the_card_on_reload`, because a count that never asks the filesystem again would pass the first test by never changing. The digest already moves when a comment lands, so the reload is what recounts
|
||||
- **A card names its campaign on the label row, before the tags, in bold.** `labels_line` draws both, `CAMPAIGN_MARK` (`~`) for the campaign and `#` for a tag, and the campaign takes the row's width first: two cards in one campaign is what a reader looking for a campaign is looking for, and the tags are the context around it. So a row too narrow for both drops the tags whole and keeps the campaign, the order `corner_line` and `project_label` already follow, and a campaign the row will not hold at all goes whole too. A ticket in neither spends no row, so **a ticket in no campaign renders exactly as it did before campaigns reached the card**
|
||||
- **`Card::campaign` is a resolved `Cell`, not a uuid**, settled at reload the way `project` and `blocked` are. `TicketItem::campaign` already carries the uuid off the pass that builds the card; the name is in another directory, so `columns_of` reads `CampaignIndex` once per project and hands it to every card. Never per draw, the rule `criteria` and `tags` already hold. The merge carries the resolved cell rather than looking it up again, for the reason it carries `blocked`: a campaign is addressed inside one `.worklane`, so a merged lookup could answer one project's uuid with another project's campaign
|
||||
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cell` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
|
||||
- **A campaign the board does not hold labels nothing**, the answer `mark_blocked` gives a dangling blocker. `campaign_cells` renders that case as `_missing_` because a metadata table is a place to report a dangling reference; a card is not
|
||||
- **`c` opens the campaign picker, and taking a campaign filters the tab's columns to its members.** Not a fifth tab: a campaign groups across the flow, so the shape of the answer is the four statuses with fewer cards in them, which is what `campaign show` already answers the question in. Every column is kept, empty ones included. The filter is applied in `reload`, where the columns are built, so nothing downstream has to ask whether a campaign is selected — the board simply holds fewer cards, and `first_match`, `done_count` and the copy key all keep working unchanged
|
||||
- **`Tab::campaign` is a uuid on the tab, not on the `Board`.** A campaign belongs to one `.worklane`, so a filter carried onto another project's tab would empty it and say nothing about why. It is looked up by uuid rather than held as an index, and a selection whose campaign has left the board is cleared by `reload` rather than left filtering the board to nothing
|
||||
- **The frame above the columns is three rows, and `Chrome` is what every measurement takes.** `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` on the bottom left. One text row, the opening line of the description. Every row spent here is a row of cards
|
||||
- **The frame above the columns has two heights, and `Chrome` is what every measurement takes.** `Chrome::campaign` is an `Option<FrameSize>`, not a bool: `None` for a tab showing the whole board, and `Collapsed` or `Expanded` for one filtered to a campaign, because both heights have to be measured the same way by everything that measures the board. `frame_rows` grew a row, so the two bools that decide the geometry became one `Chrome`, copied from `Board::chrome`: adjacent same-typed parameters are what the Rust Style rule warns about, and the draw and `follow_selection` have to measure one answer or a keypress scrolls against a board the next frame does not draw. The row indices are named (`TAB_ROW`, `CAMPAIGN_ROW`, `BOARD_ROW`, `FOOTER_ROW`), since an index written out by hand goes on meaning what it used to
|
||||
- **The whole description is carried off the one read, and the cut is on the view.** `section_prose` replaced `section_opening`, which cut to the opening line at read time: the campaign file is only in hand while the campaigns directory is being read, so what that read has to carry is everything a view might want, and `CampaignRow::summary` takes the one line the picker draws back off it. Two fields, one cut from the other, are two strings free to come from different reads of the same file
|
||||
- **`CAMPAIGN_PROSE_ROWS` is the collapsed height, and it is a constant rather than a height fitted to the description.** Three rows of prose plus a border either side. A frame that grew and shrank with the campaign would resize every column whenever the filter changed, and a reader would look for a card where the previous campaign's description had put it. It does not have to be right for the longest description, because scrolling is what covers the rest — which is also why three was affordable where one row was not
|
||||
- **The expanded height is a share, not a second constant: half of what the frame and the columns divide.** That is the screen less the tab row and the footer, so the split is even between the two of them rather than even against rows neither gets all of. Half rather than most of it for the same reason the frame is not an overlay: the columns below are the campaign's members, and a reader inspecting the campaign has to go on seeing what it is made of. Floored, so the odd row goes to the cards. `Chrome::campaign_rows` takes the height because of this, and `frame_rows` is where it is called, since that is the one place that already has an area to take a share of — which is what keeps `Chrome` itself pure and copyable from `Board::chrome` with no screen to hand
|
||||
- **The share is bounded at both ends, and `COLUMN_MIN_ROWS` is why.** `Constraint::Min(COLUMN_MIN_ROWS)` would take rows back from a frame that asked for too many, silently, and the frame's own measurement would then disagree with what is drawn — the fault `Chrome` exists to prevent. So the share is capped at what leaves the columns those rows, and floored at `CAMPAIGN_ROWS`, since expanding must never shrink the frame. On a board too short to divide, `enter` gives the collapsed height back rather than a height nothing measured. `the_expanded_share_is_bounded_at_both_ends` sweeps every height from 4 to 60, tabbed and not, because one screen that happens to work says nothing about the arithmetic
|
||||
- **The frame says the rest of what it has to say on its borders**, the trade the detail overlay makes with its title and its page indicator: `(id) ~codename · Name` on the top one, the standing on the bottom right, and `q board` then the page indicator on the bottom left. Every row spent here is a row of cards
|
||||
- **The frame's page indicator goes on the bottom border beside `q board`, not on the top beside the title.** The title is cut against the border it sits on, so an indicator up there would shorten a long campaign name the moment its description grew past three rows; and the bottom right is the standing's, which is what the frame is *about* where the indicator is only where the reader has got to in it. Dropped before `q board` when the two cannot both fit, since with a campaign selected the footer's last slot names `ctrl-c quit` and the border is the only place that says `q` gives the board back
|
||||
- **`Focus` is the third place the selection can be, and `Tab` is what holds it.** The board had a column and a card and `select_card` clamped at zero; up from the top card now reaches the frame and down returns to the column it left, since the column index is never what changed. Per tab beside the filter and the offset, so switching away and back returns to where the tab was left. `Focus::Frame` while no campaign is selected is the one state that must never exist — `select_campaign` and `reload` are what keep it from arising
|
||||
- **`Tab::selected` hands back nothing while the frame holds the selection.** Every key that acts on a card has to answer for the frame. `←→` are inert, because the frame spans the width of the board and moving the column underneath would change nothing on screen. `y` is the exception that earns its place: it copies the campaign's short id, so `y copy id` means the id of the selected thing in every state the selection can be in. No card is drawn reversed there either, since that highlight is what says which ticket a key is about
|
||||
- **`enter` routes on the focus through `Board::toggle_focused`: the frame's height on the frame, the overlay on a card.** It used to be inert on the frame for free, because `Tab::selected` hands back nothing and `toggle_detail` therefore had nothing to open. That is no longer an answer, and the routing is in `Board` rather than in the `main.rs` arm for the reason `dismiss` and `scroll_page` are
|
||||
- **`q` does not gain a layer for the expanded frame, and up and down do not take it back.** The expanded frame is the frame at its other height, not a thing laid over the board, so `q` goes on taking the campaign filter off from either height and `enter` is the only key that undoes what `enter` did. The height outlives the selection for the same reason: it is a view of the campaign the reader chose, so the columns stay short with the selection on a card. `Tab::expanded` sits beside the filter and resets where `select_campaign` and `reload` reset the focus and the offset — a different campaign opens collapsed and at the top of its own description
|
||||
- **The toggle re-clamps the frame offset, through `scroll_frame(0, screen)`.** A taller viewport has a smaller last offset than a shorter one, so where the reader was can end up past the end of the frame they just asked for. The draw clamps on its own geometry either way, but the stored value has to be clamped too or the next `pgup` counts down from a number the frame never showed. A scroll of no pages is that clamp and nothing else, which keeps it in the one place it lives
|
||||
- **The frame is out of reach from under an open ticket.** With the overlay open, up and down step through the tickets and it follows, so a selection that reached the frame would have to either close it on an arrow key or leave it showing a ticket nothing is selecting. `an_open_ticket_keeps_the_scroll_keys_from_the_frame` builds that state by hand for exactly this reason: the precedence has to hold whether or not a keypress can reach it
|
||||
- **The standing comes from the columns, not from a walk of the tree.** While a campaign is selected the columns *are* its members, done included, so `Tab::standing` counts what is already in hand rather than paying what `campaign ls` pays per campaign. Counted over every column, drawn or not: hiding done is a change to what is drawn and never to what is counted
|
||||
- **The way out is on the frame's own border, not in the footer.** `q board` sits on the thing it takes away, and the footer row was already at its width naming eight keys. Dropped whole when it and the standing would meet, the rule the page indicator follows
|
||||
- **`c` is named in the footer only on a closed board with nothing selected**, which is where a reader has to find it. Over an open ticket and on a filtered board it is left out: the frame's border then says how to put the campaign away, and the row has no cells to spare. Incomplete rather than wrong, which is the trade this row is allowed to make — what it must never do is name a key by what it used to do
|
||||
- **The footer has three states, because the selection has three places to be.** An open ticket, the frame, and the cards. On the frame it names `↓ board`, `enter expand` or `enter collapse`, the two scroll keys and `y copy id`, and leaves out `←→` because they do nothing there. It has to say which way `enter` goes, since the key is a toggle and the frame is always at one of its two heights. `↑ frame` is not named on the board, on the same trade `c` is dropped on: the frame is drawn directly above the columns and up is the key that reaches it. Nor is the way to collapse an expanded frame named from the cards, which is the same trade again — the frame is right there and `↑` reaches it
|
||||
- **`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
|
||||
@@ -256,7 +282,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **Every campaign's standing is settled at reload, in one pass over the cards.** `standings_of` counts the cards naming each uuid off the columns the reload is already holding, which is what `Standing::of` builds for `campaign ls` without the walk of the status directories that one pays *per campaign*. A keypress must not pay that, and the picker needs every campaign's standing rather than just the selected one's, since the split is what it decides. Counted before the campaign filter is applied: how far a campaign has got is not a question about what the tab is showing
|
||||
- **`Tab::standing` is gone with it.** The frame's standing is the row's, because two counts of one number are two numbers free to drift — the rule `wrapped_height` holds for the scroll. `the_standings_are_read_when_the_cards_are_and_not_per_draw` takes the status directories away after the board is built, paired with `a_member_finished_after_the_board_was_built_completes_its_campaign` for the reason the comment count's two tests are paired: a standing that never asked the filesystem again would pass the first by never changing
|
||||
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the history. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
|
||||
- `tags` is a field on `TicketItem`, filled in `collect_ticket_items` through `parse_tags`, for the reason the criteria count is. `parse_tags` splits the comma-separated field into whole trimmed values, so a caller asking for `bug` is not answered by `bugfix`, and reads absent, `_None_` and empty as the same answer
|
||||
- **A held-up card carries `BLOCKED_MARK`, `×`, after its id, in brightred.** The constant lives in `util.rs` and the relations block draws the same one, since both say the same word. A ticket waiting on an open blocker looked exactly like one that is ready, and the board is where the next thing to pick up is chosen. Not a fourth circle from Geometric Shapes: those belong to the priority meter two cells away and would read as part of that ramp. The multiplication sign is Latin-1, like the middle dot the unset priority draws, so it renders wherever the meter does
|
||||
@@ -304,7 +330,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
### The Relations Block
|
||||
- **One builder, two painters.** `relation_rows` decides which edges there are, what they are called and which direction comes first; `relation_cells` decides the layout, the mark and the colours; `paint_cells` turns cells into escapes for the CLI and `span_of` turns the same cells into ratatui spans for the board. Two builders producing one block in two shapes is a pair free to disagree about ordering or padding, which is what this shape exists to prevent
|
||||
- **`Cell` is the unit both renderers take**: a run of text and the colour it is drawn in, `None` for the default foreground. The same trick as the palette itself, where `Color::ansi()` and `From<Color> for ratatui::style::Color` keep one colour from existing for one renderer and not the other
|
||||
- **`reference_cells` is the one spelling of a cross reference**, and `reference_cell` is it painted. The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown
|
||||
- **`reference_cells` is the one spelling of a cross reference.** The relations block and the Campaign field both go through it, so a dangling reference reads the same way wherever it is shown. There was a `reference_cell` beside it that painted the cells for the CLI; once the whole body became cells the Campaign field stopped needing a string and it was the last caller, so it is gone
|
||||
- **A row carries two marks, kind then status**: what sort of edge this is, then how far the ticket at the other end has got. `blocked by × ◐ (6ce2c47) Title`. Two questions are asked of this block and one glyph could not answer both: which rows hold this ticket up, and whether the ones that do are finished
|
||||
- The status went through one bad shape first. It was a rising bar, `▁▄▆█`, as the only mark, which read as an undifferentiated column of blocks and left the kind to five long words that blur when a ticket carries several. Then the kind took the column alone and the status was lost. Both, in that order, is the answer
|
||||
- **Both directions of a kind carry one mark.** `blocked by` and `blocks` are the same edge read from two ends, and the label is what says which end you are on. `both_directions_of_a_kind_carry_one_mark` pins it
|
||||
@@ -316,11 +342,15 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **Committed and reviewing are told apart by colour alone**, both being `◐`, so a pipe cannot tell them apart: `should_use_colors` is false and both read as under way. Accepted, because `●` and `○` are the two answers usually wanted and `show` on the target settles the rest, and `assets/SKILL.md` says so outright rather than leaving an agent to infer it. Do not fix this by giving one of them a colour that means something else
|
||||
- `RelationTarget` carries the title and the status in one `Option`, because they come from the same lookup and are absent together. It was taken out when the mark keyed on the kind alone and put back one commit later, which is the cost of a field nothing reads: correct at the time, and churn either way
|
||||
- **`show` and the board carry the same mark**, decided rather than left to be discovered: the rows are one builder, so giving the CLI the mark cost nothing, and two views disagreeing about what a relation shows would be the kind of difference nobody can explain later. That makes it a change to what the CLI prints, so it is a minor
|
||||
- **`Resolved.relations` is rows, not a rendered block.** That is what lets the board style them: an escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so the block cannot arrive pre-painted. `content_parts` hands the text through already painted and the rows through untouched, which is the asymmetry the two renderers need
|
||||
- **`BodyPart` splits the body rather than building it twice.** Everything outside the relations block is rendered once, by `content_parts`; `content_trim` is that with the rows painted, and the board is that with the rows styled. `Body` is the accumulator, so a caller pushes text and rows without tracking which it pushed last
|
||||
- **`Resolved.relations` is rows, not a rendered block, and `Resolved.campaign` is cells for the same reason.** An escape sequence in a ratatui paragraph is drawn as literal bytes (6d327df), so nothing in `Resolved` can arrive pre-painted. This was the asymmetry the two renderers needed while the rest of the body was a painted string; there is no asymmetry left, since `content_parts` paints nothing at all
|
||||
- **`BodyPart` splits the body rather than building it twice.** It is `Cells` or `Relations`: everything outside the block is laid out once, by `content_parts`, and `content_trim` is that run through `paint_cells` while the board is the same cells run through `span_from`. `Body` is the accumulator, so a caller pushes cells and rows without tracking which it pushed last, and it merges a run into the trailing cell when the colour matches, because the board draws a span per cell and the body is pushed a character at a time in places
|
||||
- **`Detail.body` is a `Text`, and it is the only thing measured.** `last_offset` and the `Paragraph` both take it, so the clamp cannot wrap the body differently from the draw. `Detail::plain()` flattens it for the suite and is `#[cfg(test)]`: a second representation carried alongside the spans is a second thing to disagree
|
||||
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
|
||||
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
|
||||
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end. It now splits **per cell** rather than per part, since a `Cells` part holds many runs and a newline can fall inside any of them
|
||||
- **The whole overlay body is coloured now, and `content_parts` paints nothing.** The block used to be the only coloured part, because it arrived as rows while everything else arrived as a painted string; e4d0bb7 gave the rest the same `Cell` treatment. So the headings, the plan numbers, the criteria numbers and marks, the bold runs, the field names, the priority glyph, the tags and the grey unset values are one layout that `show` paints and the board styles. Do not reintroduce a `paint` call in `content_parts`: the flat overlay was exactly that, a renderer forced to ask for the unpainted string because the painted one held escapes
|
||||
- **`colored` still reaches `content_parts`, and it no longer means paint.** It says whether *this* renderer can carry a colour at all, and one thing turns on it: `**bold**` gives its markers up to the colour that replaces them, so a renderer with none has to keep them or the emphasis is lost rather than moved. The board passes `true`, `content_trim` passes the CLI's decision, and a piped `show` still reads its markers. Nothing else in the body consults it
|
||||
- **Magenta means bold, and `span_from` is where the board learns that.** `Color::Magenta.ansi()` is `\x1b[1;35m`, so the CLI draws every bold run bold as well as magenta, and `From<Color>` can carry only the colour. Without the modifier added on the board's side the same cell would be painted two ways, which is the one thing the shared layout exists to prevent
|
||||
- **The conversion is pinned from both ends.** `show_prints_the_same_body_it_printed_before_the_cells_conversion` holds a body with one of every painted run and asserts the CLI's output byte for byte, written from what it printed before the change, so the risk in sharing a layout, the CLI's output drifting to suit the board, fails the suite. `the_whole_body_is_styled_in_the_overlay_and_no_escape_reached_it` is the other end and is paired the way the guideline demands: a renderer that dropped every colour passes the absence, and one that went back to painting strings passes the presence
|
||||
- **The history block arrives as cells too, so nothing in the overlay is flat.** `history_cells` lays the block out once; `format_history` is those cells through `paint_cells` and the board pushes the same ones as a `Cells` part after the body, since the log lives outside the ticket file and `content_parts` never sees it. Pinned from both ends the way the body is: `show_prints_the_same_history_it_printed_before_the_cells_conversion` holds the CLI's output byte for byte, and `the_history_block_is_styled_in_the_overlay_and_no_escape_reached_it` pairs the presence with the absence (f3e099e, closing the gap e4d0bb7 left)
|
||||
|
||||
### Finding the Board
|
||||
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
|
||||
@@ -343,6 +373,31 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The tab row is drawn only when there is more than one board**, so a single board is the view it has always been. `frame_rows()` gives it `Length(0)` otherwise, which keeps the row indices the same for both cases and is shared with `card_width` and `column_text_height` for the reason `column_areas` is: geometry reproduced by hand drifts from the draw
|
||||
- `digest_of` hashes each board's `digest` into one value, so a change in any of them redraws. Do not watch only the first
|
||||
|
||||
### Who Wrote an Entry
|
||||
- **Identity is supplied, not detected.** Every option that needs no cooperation fails: a harness variable such as `CLAUDECODE` names the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor is `WORKLANE_ACTOR`, set once per session, with `--actor` as the per-call override
|
||||
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** `resolve_actor` is the only caller of `get_git_user` for an entry's author, and every entry the CLI writes goes through it. The two halves are separate pure functions, `session_actor` and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
|
||||
- **The session half is cached in a `OnceLock`, the way `should_use_colors` is:** neither the variable nor the git user can change mid-run, and the fallback costs a `git config` subprocess. `session_actor` takes the git user as a closure so that subprocess is not run when the variable already answered
|
||||
- An **empty `WORKLANE_ACTOR` counts as unset**, the convention `colors_wanted` follows for `NO_COLOR`, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one
|
||||
- **The actor is free text, checked against nothing**, like the `chown` user: there is no registry of actors, and the same reason `ls --tag` refuses to validate a tag
|
||||
- **It was `comment --owner`, renamed with no alias.** Owner is the ticket's assignee and has one writer, `chown`; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splitting `set` and `chown` avoided. `the_owner_flag_is_gone` pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
|
||||
- **`add --owner` and `campaign add --owner` still default to the git user, deliberately.** Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported
|
||||
- **An entry does not record whether the call had a terminal.** It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
|
||||
- **Set it in the agent's configuration, not per call.** `env` in `~/.claude/settings.json` reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no `env` block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around `opencode`. Both are documented in `assets/SKILL.md` rather than assumed
|
||||
|
||||
### The History Log
|
||||
- **The log is the comments directory with the kind named in it.** It was already an append-only log with one event kind: one file per entry under `.worklane/history/<uuid>/`, stamped to the microsecond and written with `create_new`. Adding `status`, `owner` and `tags` beside `comment` needed no new mechanism, which is why there is no separate journal file and no database
|
||||
- **What is not logged, deliberately:** ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
|
||||
- **`--clear` is logged, since it is the same field going somewhere.** `chown --clear` and `set --clear tags` write an entry whose after-value is the sentinel the ticket now holds, `_Not set_` or `_None_`. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does
|
||||
- **The kind is read from the file and only counted from the filename.** `parse_entry` matches the leading marker; `kind_from_stem` splits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader
|
||||
- **A file with no marker is a comment**, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command: `entry_content(Kind::Comment, ..)` is byte for byte what `cmd_comment` wrote before this module, so nothing is rewritten and either version can read the other's board
|
||||
- **The old directory is adopted, not migrated.** `adopt_comments` renames `comments` to `history` on the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. **A board holding both is refused**, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it
|
||||
- **An entry is written after the edit it describes, never before.** A refused move, a refused chown and a failed save log nothing, which is what `a_refused_move_writes_nothing` and `a_failed_edit_writes_nothing` pin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it
|
||||
- **A no-op edit writes nothing either, and `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them
|
||||
- **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it
|
||||
- **A mechanical entry renders as one line and a comment as it always did.** A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to `Kind::LABEL_WIDTH`, `status` being the longest of the three, so the bodies line up under each other
|
||||
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
|
||||
- **`set --actor` reaches only the entry `--tags` writes**, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries
|
||||
|
||||
### Shipping the Agent Assets
|
||||
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
|
||||
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
|
||||
@@ -370,11 +425,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
|
||||
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
|
||||
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
|
||||
- **The README command table has the same guard, `every_subcommand_has_a_row_in_the_readme_command_table` in `command.rs`.** The skill and the table are the two places a command is discovered, one by an agent and one by a person, and the skill was the only one under test: `campaign` and `assign` shipped in 0.12.0 and were still absent from the table at 0.20.0, e6e3a1b, along with the `--campaign` flag on the `ls` row. It walks clap's own subcommands, one level of nesting included, against the `|` lines of `README.md`, so a new command fails the suite until the table lists it. `help` is excluded, being clap's. The tag subcommands are named in a `PENDING` list rather than skipped, since f7dd1a1 rewrites that row and emptying the list is part of closing it
|
||||
|
||||
### Color and Output
|
||||
- Use `color_text()` for coloured output — it respects `should_use_colors()` (terminal detection), and `paint()` is the same with the decision passed in
|
||||
- **`color_text()` is for the CLI's own printing only. Anything reachable from `content_trim` takes the decision as an argument and calls `paint()`**, because the board renders with colour off and an escape sequence in a ratatui paragraph is drawn as literal bytes. `nothing_the_body_renders_asks_the_terminal_for_the_colour_decision` scans this file and fails on a new caller; the allowlist is `ambiguous`, which builds a failed-search message for stderr
|
||||
- A function that takes an `enabled` flag must use it all the way down. `colorize_bold` honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function
|
||||
- A function that takes an `enabled` flag must use it all the way down. The inline pass honoured its flag on the early return and then asked `should_use_colors()` for the bold run, which made the flag a lie in half the function. The better answer, where it fits, is to take no flag: `ordered_cells` and `metadata_value_cells` return the colour rather than a decision about it
|
||||
- **A test that asserts an absence has to be paired with one that asserts the presence.** The guard for this, an assert that the detail view holds no escape byte, could not fail: a test binary has no tty, so `should_use_colors()` was false and the leaking branch was never taken. The pair is now `content_trim(.., false)` has no escape and `content_trim(.., true)` still colours, which pins the flag as the only thing that decides
|
||||
- **The palette is the `Color` enum, not a string.** `Color::ansi()` gives the CLI its SGR sequence and `From<Color> for ratatui::style::Color` gives the TUI its equivalent, so a colour that exists for one renderer and not the other is a compile error. The stringly-typed version needed a test for exactly that, and a missing entry silently produced an empty prefix, which is how `magenta` came to be undefined
|
||||
- Reset color with `\x1b[0m` after colored text
|
||||
@@ -391,6 +447,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Priority ramp → brightred (1), red (2), orange (3), cyan (4), grey (5). Green is deliberately absent: it means title
|
||||
- Relation kind mark → brightred `×` blocked by and blocks, cyan `→` relates to, orange `←` regression of and regressed by. A small ramp inside one column, the way the priority meter is: the mark says which kind of edge the row is, so none of these three is a colour standing in for the uuid or the title beside it. Brightred on the cross rather than red, because the id one cell to its right is red and the two would blend. It is the colour and the glyph a held-up card already carries, which is the point: one vocabulary for blocking
|
||||
- Relation status mark → grey `○` backlog, orange `◐` committed, cyan `◐` reviewing, green `●` done, grey `?` for a target the board does not hold. The second ramp in that column: the shape says how far the target has got and the colour tells the two middle stages apart, since both are half circles. **Green is here and deliberately absent from the priority ramp**, where it would sit on a whole line and read as a title; on a one-cell mark with no title behind it, it is the obvious colour for finished and nothing else wants it. Orange keeps the meaning it already has, Status, and grey keeps unset for the one row with no status to show
|
||||
- Markdown link → cyan, markers and url kept. Not a new meaning for the colour: the plan numbers, the criterion numbers and the `relates to` mark are already cyan inside a rendered body, and a link is the same kind of thing, a pointer the reader may follow rather than a value. The url is not hidden behind the text the way a renderer would hide it, because `show` prints to a terminal worklane cannot assume will make it clickable, and a link whose target cannot be read is worse than a long line
|
||||
- Chrome → grey. The footer's key names, a rendered `[ ]`, and the overlay's page indicator. Not a new slot: grey already means "what a reader skips", which is the other half of the unset-value meaning, and none of these is a value. The indicator in orange would read as the title it faces across the overlay, in cyan as a timestamp, and in the priority ramp's colours as a level
|
||||
- Campaign label → its codename through `tag_color`, bold, marked `~`. The colour is what groups a campaign across the cards that carry it, which is exactly what a tag's colour is for, and one word is one colour in every view because `tag_color` is a pure function of it. The mark and the bold are what tell it from a tag on a row that holds both: the mark is not `#`, or the row would read as a list of tags with a stranger in it, and not `@`, which reads as a person on every board anyone has used. `Codename` in a metadata table takes the colour without the mark, since the field name has already said what it is
|
||||
- Campaign label with no codename → grey. The label is then the short id, and grey keeps a reserved meaning off a `TAG_COLORS` slot in the one case where it would land on one: red is the uuid's everywhere else, and grey already means what a reader skips, which is what a campaign with no codename has to say for itself
|
||||
@@ -402,8 +459,10 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- Grey is indexed colour 8 in the 256-colour form, not SGR 90 or 37. Both of those failed on a real palette: 90 leans on the bright-black slot and 37 can sit on top of the default foreground. `\x1b[38;5;8m` is byte for byte what crossterm emits for ratatui's `Color::DarkGray`, the grey frig and pantop use for dimmed rows
|
||||
|
||||
### Code Organization
|
||||
- Colorization functions (`colorize_ordered`, `colorize_bold`, `content_trim_colored`) handle markdown formatting. `colorize_line` is gone: it was a `pub` alias for `colorize_bold` with one caller, and the only thing it added was asking the terminal
|
||||
- `show` renders the Metadata section as a two column table via `render_metadata_table`, not line by line. Column width is measured on the raw field names in characters and padding is applied before anything is styled: measuring a coloured string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
|
||||
- **`history.rs` owns the log end to end**: the path, the kinds, the parse, the write, the count and the render. It came out of `util.rs` and `handlers.rs`, where the reader, the writer, the counter and the renderer sat in three files and one of them was 5,500 lines. The test for the reason is the module doc: a reader asking what an entry is has one file to open, the way `campaign.rs` and `tag.rs` answer their own questions
|
||||
- The body's painters return cells, not strings: `ordered_cells`, `inline_cells`, `metadata_cells`, `metadata_value_cells`, `tag_cells` and `push_heading`. `content_trim_colored` is the CLI entry point and `paint_cells` is the only thing that writes an escape. `colorize_line` is gone: it was a `pub` alias for the bold pass with one caller, and the only thing it added was asking the terminal
|
||||
- **`inline_cells` walks the line once for both inline markers**, `**bold**` and `[text](url)`, rather than running one pass over the output of the other. A second pass would be scanning text that already holds escape sequences, and `\x1b[36m` carries an opening bracket, so the link scan would take the escape for markup. The source is the only string in which either marker means what it says. It was `colorize_bold` while links lived in a branch of their own in `content_parts`; that branch is gone, which is also what gives the criteria text and the metadata `Other` rows their links, since those already went through this function
|
||||
- `show` renders the Metadata section as a two column table via `metadata_cells`, not line by line. Column width is measured on the raw field names in characters and the padding goes into a cell of its own, so nothing is ever measured with a colour on it: measuring a painted string counts its escapes towards its width. `paint()` is `color_text()` with the colour decision passed in, which is what lets a test render both ways in one process
|
||||
- The title is printed once, by `cmd_show`. `content_trim_colored` skips the `# ` heading in the file content
|
||||
- Rules under headings are measured on the displayed name in characters, never on the raw line or in bytes
|
||||
- `resolve_ticket()` scans all status directories — it's the single source for ticket lookup by UUID prefix, title, or filename
|
||||
@@ -430,12 +489,12 @@ and this file is for what someone changing worklane's own code needs.
|
||||
### Version Bumps
|
||||
- Before every commit, decide whether the change warrants a version bump in `Cargo.toml`
|
||||
- Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious
|
||||
- **`make patch`, `make minor` and `make major` do the mechanics**, run after the commit is in: each bumps `Cargo.toml` and the `worklane` entry in `Cargo.lock`, appends `, and bump to <version>` to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-tagged `HEAD` and on a `HEAD` that is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push
|
||||
- Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0
|
||||
- **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View
|
||||
- **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features
|
||||
- No bump for docs-only, tests-only or `--fixup` commits
|
||||
- When one body of work spans several commits, bump once on the final commit rather than on each
|
||||
- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump
|
||||
- Every bump gets a matching annotated tag, `v<version>`, on the bump commit — a bumped version is never left untagged
|
||||
- Tag locally only; never push a tag unless asked
|
||||
- `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another
|
||||
|
||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.25.0"
|
||||
version = "0.29.1"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.25.0"
|
||||
version = "0.29.1"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
# Release helpers.
|
||||
#
|
||||
# `make patch|minor|major` bumps the version in Cargo.toml and Cargo.lock, folds
|
||||
# that bump into the last commit, and tags it. Everything is one action so a
|
||||
# release cannot end up half-done: no version bump left untagged, no tag without
|
||||
# a bump.
|
||||
|
||||
.PHONY: help patch minor major version release install
|
||||
|
||||
help:
|
||||
@echo "make patch bump $(CURRENT) -> next patch, amend into HEAD, tag"
|
||||
@echo "make minor bump $(CURRENT) -> next minor, amend into HEAD, tag"
|
||||
@echo "make major bump $(CURRENT) -> next major, amend into HEAD, tag"
|
||||
@echo "make version print the current version"
|
||||
@echo "make install cargo install --path . && worklane install-skill"
|
||||
|
||||
# Read from the [package] table of Cargo.toml, which is the version the binary
|
||||
# reports through `--version`, so it is the single source of truth. The name is
|
||||
# what finds this crate's own entry in Cargo.lock.
|
||||
PACKAGE = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^name *= *"/{print $$2; exit}' Cargo.toml)
|
||||
CURRENT = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^version *= *"/{print $$2; exit}' Cargo.toml)
|
||||
|
||||
# 1 appends ", and bump to <version>" to the amended commit's subject; empty
|
||||
# leaves the message alone.
|
||||
AMEND_SUBJECT = 1
|
||||
|
||||
version:
|
||||
@echo $(CURRENT)
|
||||
|
||||
patch: BUMP = patch
|
||||
minor: BUMP = minor
|
||||
major: BUMP = major
|
||||
patch minor major: release
|
||||
|
||||
# A release rewrites the last commit, so refuse anything that would make that
|
||||
# rewrite lose work or orphan a tag.
|
||||
release:
|
||||
@set -e; \
|
||||
if ! git rev-parse -q --verify HEAD >/dev/null 2>&1; then \
|
||||
echo "error: no commits yet, so there is no commit to fold a version bump into. Commit first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if [ -n "$$(git status --porcelain)" ]; then \
|
||||
echo "error: working tree is dirty. Commit or stash first, and decide whether that work belongs in this version:" >&2; \
|
||||
git status --short >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if [ -n "$$(git tag --points-at HEAD)" ]; then \
|
||||
echo "error: HEAD is already tagged $$(git tag --points-at HEAD | paste -sd' '). Amending it would leave that tag on an orphaned commit. Commit something first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
if upstream=$$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) && \
|
||||
git merge-base --is-ancestor HEAD "$$upstream" 2>/dev/null; then \
|
||||
echo "error: HEAD is already pushed to $$upstream. Amending it would need a force push. Commit something first." >&2; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
current="$(CURRENT)"; \
|
||||
if [ -z "$$current" ]; then echo "error: no version found in the [package] table of Cargo.toml" >&2; exit 1; fi; \
|
||||
new=$$(echo "$$current" | awk -F. -v kind=$(BUMP) '{ \
|
||||
if (NF != 3) exit 1; \
|
||||
if (kind == "patch") printf "%d.%d.%d\n", $$1, $$2, $$3 + 1; \
|
||||
else if (kind == "minor") printf "%d.%d.0\n", $$1, $$2 + 1; \
|
||||
else printf "%d.0.0\n", $$1 + 1 }'); \
|
||||
if [ -z "$$new" ]; then echo "error: cannot bump version '$$current': expected major.minor.patch" >&2; exit 1; fi; \
|
||||
if git rev-parse -q --verify "refs/tags/v$$new" >/dev/null; then \
|
||||
echo "error: tag v$$new already exists" >&2; exit 1; \
|
||||
fi; \
|
||||
awk -v v="$$new" '/^\[package\]/{p=1} /^\[/ && !/^\[package\]/{p=0} p && /^version *= *"/{sub(/"[^"]*"/, "\"" v "\"")} {print}' Cargo.toml > Cargo.toml.bump; \
|
||||
mv Cargo.toml.bump Cargo.toml; \
|
||||
git add Cargo.toml; \
|
||||
if [ -f Cargo.lock ] && git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then \
|
||||
awk -v v="$$new" -v pkg="$(PACKAGE)" '$$0 == "name = \"" pkg "\""{f=1} f && /^version = "/{sub(/"[^"]*"/, "\"" v "\""); f=0} {print}' Cargo.lock > Cargo.lock.bump; \
|
||||
mv Cargo.lock.bump Cargo.lock; \
|
||||
git add Cargo.lock; \
|
||||
fi; \
|
||||
if [ -n "$(AMEND_SUBJECT)" ]; then \
|
||||
subject=$$(git log -1 --format=%s | sed -E 's/, and bump to [0-9]+\.[0-9]+\.[0-9]+$$//'); \
|
||||
body=$$(git log -1 --format=%b); \
|
||||
if [ -n "$$body" ]; then \
|
||||
git commit --quiet --amend -m "$$subject, and bump to $$new" -m "$$body"; \
|
||||
else \
|
||||
git commit --quiet --amend -m "$$subject, and bump to $$new"; \
|
||||
fi; \
|
||||
else \
|
||||
git commit --quiet --amend --no-edit; \
|
||||
fi; \
|
||||
git tag -a "v$$new" -m "v$$new"; \
|
||||
echo "$$current -> $$new, tagged v$$new on $$(git rev-parse --short HEAD) ($$(git log -1 --format=%s))"
|
||||
|
||||
install:
|
||||
cargo install --path .
|
||||
worklane install-skill
|
||||
@@ -5,29 +5,38 @@ 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, 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` 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 or the campaign frame, whichever the selection is on, with a page indicator on its border while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold, and a comment count in its bottom right corner, the number then `❞` in cyan, before the criteria count and absent entirely when nobody has commented; while one is selected a frame above the columns names it, shows three rows of its description and says how far it has got, and `q` on its border gives the whole board back; up from the top card of a column moves the selection to that frame, where the scroll keys page through the description, `enter` gives it half the board and takes the rows back again, and down returns to the column it came from, leaving the frame at whatever height it was. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
|
||||
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring. A campaign is addressed the same way, plus its exact codename, which wins over all three. Ends with the ticket's history: every comment on it and every change to its status, owner or tags, oldest first, each naming who made it |
|
||||
| `worklane mv <id> --status <target> [-f]` | Moves ticket between statuses. Default: forward only, one stage at a time. `-f` bypasses both restrictions. Records a `status` entry in the ticket's history, after the move: a refused or no-op move records nothing. `--actor` names the writer of that entry |
|
||||
| `worklane set <ticket>` | Replaces fields with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--priority`. At least one required. Changing the title renames the file, keeping the UUID. `--clear <field>` returns a field to unset instead, repeatable, taking `due`, `tags`, `priority`, `description`, `acceptance` or `plan`, and writing back exactly what `add` writes for a field it was never given. No `title`, which addresses the ticket, and no `owner`, which is `chown`'s. Replacing and clearing the same field in one call is refused. `--tags` records a `tags` entry in the ticket's history, with the tags before and after, and it is the only field of this command's that is logged; `--actor` names the writer of that entry |
|
||||
| `worklane append <ticket>` | Adds to a section with `--description`, `--acceptance`, `--plan`. At least one required. The description gains a paragraph; list items go on the end, steps numbered on from the last |
|
||||
| `worklane relate <ticket>` | Records an edge to another ticket with `--blocked-by`, `--regression-of` or `--relates-to`, each repeatable. At least one required. Only the ticket named is written; `show` derives the other end by scanning. `mv` refuses to move a ticket blocked by one that is not done, unless `-f` |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to |
|
||||
| `worklane chown <user> <ticket>` | Sets the Owner field, the only command that writes it. Free text, checked against nothing. User first and ticket second, after Unix `chown`. `worklane chown --clear <ticket>` returns the field to unset, taking the ticket in the flag since there is no user to give, and not to the git user `add` falls back to. Records an `owner` entry in the ticket's history, with the owner before and after; `--actor` names who made the change, which is not the same as the user argument |
|
||||
| `worklane check <ticket> [criteria...]` | Ticks acceptance criteria, each by number as shown by `show` or by a substring. Several in one call, or `all` for every one of them. Prompts with the numbered list if none is given, or errors with it when there is no terminal |
|
||||
| `worklane uncheck <ticket> [criteria...]` | Unticks acceptance criteria, addressed the same way |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title |
|
||||
| `worklane comment <ticket> <body>` | Adds a comment to a ticket by UUID or title. The author is `--actor`, or `WORKLANE_ACTOR`, or the git user, in that order |
|
||||
| `worklane campaign add` | Files a campaign in `.worklane/campaigns/` with `--title`, `--description`, `--codename` and `--owner`. A campaign has no status: its state is derived, open until every member is done. `--codename` is one word to call it by, `v1` or `beaver`, which is what the board draws on every card in it and what every command that takes a campaign will also resolve it by |
|
||||
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, and `--codename`. At least one required. The only way to change a campaign after it is filed, and the way a campaign filed before codenames existed gets one. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. No `--description`: replacing prose without an `append` to add a paragraph is half a pair |
|
||||
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title and how many members are done. `--ids` prints one per line as the id, a tab and the title, unstyled, for a script or a completion |
|
||||
| `worklane campaign set <campaign>` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` |
|
||||
| `worklane campaign append <campaign>` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket |
|
||||
| `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title, how many members are done, and the state that count derives: `[open]` until every member is done and `[done]` after. A campaign nothing has been filed against reads `no members` and carries no state, being neither. `--ids` prints one per line as the id, a tab and the title, unstyled and without the counts, which read every ticket on the board, for a script or a completion |
|
||||
| `worklane campaign show <campaign>` | Shows a campaign and its members grouped by status, done included, since what is finished against what is left is the question a campaign asks |
|
||||
| `worklane assign <campaign> <ticket>` | Puts a ticket in a campaign, the only command that writes the Campaign field. Campaign first and ticket second, after `chown`. A ticket is in at most one, so assigning one that already belongs somewhere moves it |
|
||||
| `worklane tags` | Lists the tags the board carries as the tag, a tab and how many tickets carry it, one per line, unstyled and alphabetical. Case sensitive like `ls --tag`, so `bug` and `Bug` list separately and land next to each other. Every status, done included. The one command that answers what tags exist rather than what carries a tag already known |
|
||||
| `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-skill [skill]` | Writes the embedded agent skills to `~/.claude/skills/<skill>/SKILL.md`, which Claude Code and opencode both read. Four ship: `worklane` teaches the CLI, `worklane-review` reviews a finished ticket against the code that claims to close it, `worklane-plan` grooms the board as a whole, its priorities, due dates, tags and campaigns, and `worklane-admin` sets a board up and repairs one, its tag vocabulary and the faults a board can develop. Every document unless one is named. Leaves a modified copy alone unless `--force`; `--print` writes one to stdout instead and needs the name |
|
||||
| `worklane install-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
|
||||
|
||||
## Environment
|
||||
|
||||
| Variable | Effect |
|
||||
|----------|--------|
|
||||
| `WORKLANE_ACTOR` | Who every entry the CLI writes is attributed to: a comment, and the `status`, `owner` and `tags` entries `mv`, `chown` and `set --tags` record. Set it once, in the environment an agent runs in, and every call it makes is attributed to it instead of to the git user of whoever's machine it is on. `--actor` overrides it per call, an empty value counts as unset, and with neither supplied the author is the git user and then `unknown`. Free text, checked against nothing |
|
||||
| `NO_COLOR` | Set and non-empty turns colour off, whatever the value, per no-color.org. Colour is also off when output is not a terminal, and when `TERM` is `dumb` or empty |
|
||||
| `XDG_CONFIG_HOME` | Where `install-tool` looks for opencode's config root, `$XDG_CONFIG_HOME/opencode`, defaulting to `~/.config`. `install-skill` does not follow it: `~/.claude` is not an XDG path |
|
||||
|
||||
## Completions
|
||||
|
||||
```sh
|
||||
@@ -77,3 +86,20 @@ Whether a truncated pipe reports 141 or 0 depends on the size of the output, not
|
||||
the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole
|
||||
and the writer never learns the reader left, giving 0. Only output past that gets far
|
||||
enough to be cut off. Either way nothing is printed to stderr.
|
||||
|
||||
## Releasing
|
||||
|
||||
```sh
|
||||
make patch # 0.27.1 -> next patch
|
||||
make minor # 0.27.1 -> next minor
|
||||
make major # 0.27.1 -> next major
|
||||
```
|
||||
|
||||
Each bumps `Cargo.toml` and `Cargo.lock`, folds that bump into the last commit, and tags it
|
||||
`v<version>`. One action, so no bump is left untagged and no tag lands without a bump. In this repo
|
||||
it also appends `, and bump to <version>` to the commit's subject, the way the release commits
|
||||
before it read.
|
||||
|
||||
It refuses to run when the working tree is dirty, when `HEAD` is already tagged, or when `HEAD` is
|
||||
already pushed. The first asks you to decide whether that work belongs in the version; the other two
|
||||
mean the amend would orphan a tag or need a force push.
|
||||
|
||||
+323
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: worklane-admin
|
||||
description: Set up and repair a worklane board itself, whatever it tracks: design and annotate the tag vocabulary with `worklane tags`, retire or rename a tag, and fix a board whose files and fields disagree, such as a ticket missing from `ls`, a duplicated id, a stray temp file or a move that will not go through. Use when the subject is the board's own configuration or health. Not for filing, working or reviewing a ticket, and not for priorities, due dates or campaigns.
|
||||
---
|
||||
|
||||
# Administering a worklane board
|
||||
|
||||
For "set up a board for this", "what tags should this board have", "add a tag", "what
|
||||
does this tag mean", "the board is in a weird state", "this ticket has gone missing".
|
||||
The subject is the board itself: the vocabulary it files against, and the parts that can
|
||||
come apart.
|
||||
|
||||
The CLI is the `worklane` skill: the statuses, how a ticket is addressed, which command
|
||||
owns which field. Read it too.
|
||||
|
||||
**This is not `worklane-plan`.** That skill grooms the work: priorities, due dates,
|
||||
retagging tickets, campaigns. This one decides what the tags *are* and puts the board
|
||||
back together. The line between them is the tag section: designing and annotating the
|
||||
vocabulary is here, applying it across tickets is there.
|
||||
|
||||
## A board is not only for software
|
||||
|
||||
Everything below holds for a board tracking a product strategy, a house move or a term's
|
||||
teaching, and the worked examples say so. What changes between domains is the tags, never
|
||||
the shape. Nothing in worklane knows what your tickets are about.
|
||||
|
||||
Two things you do not get to configure, whatever the board is for:
|
||||
|
||||
- **The four statuses.** `backlog`, `committed`, `reviewing`, `done`, in that order, one
|
||||
step at a time. There is no way to rename them or add a fifth. If a board wants a
|
||||
waiting-on-someone-else state, that is a tag, and the ticket stays in `committed`.
|
||||
- **The fields.** Priority 1 to 5, Due, Owner, Tags, Campaign. A board that wants a
|
||||
concept these do not cover expresses it as a tag or a campaign, not as a new field.
|
||||
|
||||
So the tag vocabulary is where a board is fitted to its subject, and it is most of this
|
||||
document.
|
||||
|
||||
## Starting a board
|
||||
|
||||
```
|
||||
worklane init # in the directory the board belongs to
|
||||
```
|
||||
|
||||
Which directory decides which board. Commands walk up from the working directory to the
|
||||
nearest `.worklane`, so a board in `~/house` answers every `worklane` run from anywhere
|
||||
under `~/house` and nowhere else.
|
||||
|
||||
`init` makes the four status directories, the campaigns directory and an empty `tags.md`.
|
||||
Run on a board that already exists it prints a line and changes nothing, which is what
|
||||
makes it safe to run when you are not sure.
|
||||
|
||||
Then declare the vocabulary before the tickets pile up. Tags applied for months are far
|
||||
harder to change than tags agreed once, because changing one means rewriting every ticket
|
||||
carrying it.
|
||||
|
||||
## Designing a tag vocabulary
|
||||
|
||||
A tag is a word a ticket carries so the board can be cut by it later. `worklane ls --tag
|
||||
kitchen` is the whole payoff, so the test of a good vocabulary is whether the cuts it
|
||||
allows are cuts anyone wants.
|
||||
|
||||
### Work in axes
|
||||
|
||||
An axis is one question every ticket on this board can answer, with a small closed set of
|
||||
answers. Pick two or three axes and keep them apart. Nearly every vocabulary that goes
|
||||
bad is one where two axes were mixed into one pile of words.
|
||||
|
||||
A software tool:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `feature`, `bug`, `chore`, `docs` |
|
||||
| Area | `cli`, `tui`, `api`, `build` |
|
||||
|
||||
A product strategy:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `research`, `decision`, `experiment`, `writeup` |
|
||||
| Audience | `enterprise`, `self-serve`, `internal` |
|
||||
|
||||
A household:
|
||||
|
||||
| Axis | Answers |
|
||||
|---|---|
|
||||
| Kind | `repair`, `errand`, `admin`, `cleaning` |
|
||||
| Room | `kitchen`, `garden`, `garage`, `car` |
|
||||
|
||||
Same shape, nothing in common. Derive the axes from the questions somebody will actually
|
||||
ask this board, not from a template: if nobody will ever ask "show me everything in the
|
||||
garage", `garage` is not earning its place.
|
||||
|
||||
### The rules
|
||||
|
||||
- **A tag is for kind, not for state.** State is the status directory. A `doing` tag
|
||||
beside `committed`, a `blocked` tag beside a `blocked by` relation, a `done` tag at all:
|
||||
each is a second copy of something the board already knows, and the copy is the one that
|
||||
goes stale.
|
||||
- **A tag is not a goal.** Everything for one outcome is a campaign, which has a title, a
|
||||
description and a state derived from its members. `worklane campaign` owns that;
|
||||
`worklane-plan` decides what belongs in one.
|
||||
- **A tag is not a field.** No `p1` beside Priority, no `alice` beside Owner, no `august`
|
||||
beside Due. The field is the writer and the tag will disagree with it.
|
||||
- **A tag is not a person.** Owner is a field, and `chown` writes it.
|
||||
- **Two axes, not two words for one thing.** Before adding a word, say which axis it is
|
||||
on. If it does not fit one, either it is a new axis, which is a decision, or it is a
|
||||
private note, which is not a tag.
|
||||
- **Around a dozen tags, up to twenty.** Past that nobody remembers the vocabulary, so
|
||||
they invent a near-duplicate instead of reusing what is there. Fewer, broader tags beat
|
||||
a long tail nobody can recall.
|
||||
- **Singular or plural, pick one and keep to it.** `bug`/`bugs` and `chore`/`chores` are
|
||||
the commonest way a board ends up with two words for one idea.
|
||||
- **Case matters.** `Bug` and `bug` are two tags to `--tag`, to `tags` and to the colour
|
||||
a card is drawn in. Lowercase everything unless there is a reason.
|
||||
|
||||
### How many tags per ticket
|
||||
|
||||
One per axis is the target: a ticket is one kind of thing in one area. A ticket that wants
|
||||
three areas is usually two tickets, and a ticket with no tag at all is invisible to every
|
||||
question asked by tag.
|
||||
|
||||
## Annotating a tag
|
||||
|
||||
```
|
||||
worklane tags # every tag, its count and what it means
|
||||
worklane tags add kitchen --annotation "..." # declare one, and say what it means
|
||||
worklane tags set kitchen --annotation "..." # change what it means
|
||||
```
|
||||
|
||||
`.worklane/tags.md` holds one section per declared tag, the tag as the heading and its
|
||||
annotation under it. It is what a person opens to find out what the board means by a word,
|
||||
and it is what an agent reads before choosing one.
|
||||
|
||||
**Declaring a tag tags nothing, and tagging a ticket declares nothing.** The two lists are
|
||||
separate on purpose: the counts come from what the tickets carry, `tags.md` records what
|
||||
the board agreed on, and the difference between them is the thing worth looking at. A tag
|
||||
carried by tickets but never declared is a word somebody invented in a hurry.
|
||||
|
||||
`worklane tags` reports both, as the tag, a tab, the count, and a tab and the annotation's
|
||||
opening line for a tag that is declared. So the two cases worth finding read off the
|
||||
listing: a tag at a count of zero is declared and nobody has reached for it, and a tag with
|
||||
no annotation column at all is carried and was never declared.
|
||||
|
||||
### What an annotation has to say
|
||||
|
||||
The definition is the easy half and does the least work. What stops drift is the boundary
|
||||
against the neighbouring tag, so write that.
|
||||
|
||||
Worthless, because nobody was ever unsure of this:
|
||||
|
||||
```
|
||||
worklane tags add bug --annotation "Bugs."
|
||||
```
|
||||
|
||||
Useful, because it answers the question somebody was actually about to get wrong:
|
||||
|
||||
```
|
||||
worklane tags add bug \
|
||||
--annotation "Behaviour that contradicts what the tool says it does, reproducible from a described state." \
|
||||
--annotation "" \
|
||||
--annotation "Not for something missing. A gap is a feature, however obvious the gap is."
|
||||
```
|
||||
|
||||
The same for a household board:
|
||||
|
||||
```
|
||||
worklane tags add repair \
|
||||
--annotation "Something that worked and now does not." \
|
||||
--annotation "" \
|
||||
--annotation "Not for an improvement to something that works, which is a project, and not for a thing that needs replacing rather than fixing."
|
||||
```
|
||||
|
||||
Repeat `--annotation` for more lines, and pass an empty one for a paragraph break. Three
|
||||
lines is plenty: a definition, then the boundary.
|
||||
|
||||
Write an annotation for every tag, including the obvious ones. The obvious tags are the
|
||||
ones two people quietly disagree about.
|
||||
|
||||
### Traps
|
||||
|
||||
- `tags add` refuses a tag that is already declared, and `tags set` refuses one that is
|
||||
not. Each names the other, so the refusal tells you which you wanted.
|
||||
- A tag cannot contain a comma, because a comma is what separates one tag from the next in
|
||||
the Tags field. Surrounding spaces are trimmed.
|
||||
- A tag you have declared and never applied lists at a count of zero. That is not a fault;
|
||||
it is the file and the board disagreeing, which is the state that tells you the
|
||||
vocabulary has not landed yet.
|
||||
- Nothing removes a declaration. There is no `tags rm`, so a tag declared in error stays
|
||||
in the file with whatever its annotation says. Say it is retired in the annotation.
|
||||
|
||||
## Changing the vocabulary later
|
||||
|
||||
### Renaming a tag
|
||||
|
||||
There is no rename. The tag is the key, so it means rewriting the Tags field of every
|
||||
ticket carrying it, one at a time:
|
||||
|
||||
```
|
||||
worklane ls --tag bugs --ids # every ticket carrying the old word
|
||||
worklane show 1b78a24 # read the whole Tags field of each
|
||||
worklane set 1b78a24 --tags bug,cli # restate all of them, with the new word
|
||||
worklane tags add bug --annotation "..."
|
||||
```
|
||||
|
||||
**`--tags` replaces the whole field.** Restate every tag the ticket should keep or the
|
||||
ones you leave out are gone, with no undo. This is the most destructive command on the
|
||||
board. Read the ticket's current tags before writing, never from memory, and run
|
||||
`worklane tags` before and after: a count that moved where nothing was meant to change is
|
||||
a tag lost to that rule.
|
||||
|
||||
Propose the whole list of edits and wait for approval before applying any of them, the way
|
||||
`worklane-plan` requires for a sweep. The reason is the same: nothing records what a field
|
||||
held before you wrote to it.
|
||||
|
||||
### Retiring a tag
|
||||
|
||||
Take it off the tickets the same way, then leave the declaration saying it is retired and
|
||||
what replaced it. A tag with a count of zero and an annotation pointing elsewhere is a
|
||||
better answer than a word that simply vanishes, because the next person will otherwise
|
||||
reinvent it.
|
||||
|
||||
## Repairing a board
|
||||
|
||||
Every repair here has been run against a real board. Work by symptom.
|
||||
|
||||
**The rule that does not bend: do not edit a ticket file.** The filename, the `Status`
|
||||
field and the directory have to agree, and the commands are what keep them agreeing. The
|
||||
two exceptions below are files no command owns, and they are marked as such.
|
||||
|
||||
### A ticket has vanished from `ls`
|
||||
|
||||
`worklane ls` leaves `done` out of its listing, though it still counts it at the top. So
|
||||
first check `worklane ls done`. If it is there and should not be, its file has been moved
|
||||
into the wrong directory by hand or by a restore.
|
||||
|
||||
The repair is two moves, not one:
|
||||
|
||||
```
|
||||
worklane mv 1b78a24 --status reviewing -f
|
||||
worklane mv 1b78a24 --status done -f
|
||||
```
|
||||
|
||||
`mv` reads the current status from the *directory*, so moving it to the status the
|
||||
directory already says it is in is refused as a no-op and the field stays wrong. Moving it
|
||||
away and back rewrites the field. Check with `worklane show 1b78a24`, whose `Status` line
|
||||
is read from the file rather than from where it sits.
|
||||
|
||||
### A command says the id matches several tickets
|
||||
|
||||
```
|
||||
Multiple tickets found matching 'bf2dc18':
|
||||
1. (bf2dc18) Alpha [backlog]
|
||||
2. (bf2dc18) Alpha [done]
|
||||
```
|
||||
|
||||
The same file exists in two status directories, usually from a copy or a half-finished
|
||||
restore. The ticket is now unaddressable: every command resolves before it acts, so `show`
|
||||
and `mv` fail the same way and cannot be used to fix it.
|
||||
|
||||
**File exception.** Read both with `cat`, keep the one whose `Status` field agrees with
|
||||
the directory it is in, and delete the other. If neither agrees, keep either and repair it
|
||||
as above. Then confirm with `worklane show`.
|
||||
|
||||
### A move is refused by a blocker
|
||||
|
||||
```
|
||||
Cannot move 'Beta' while it is blocked by:
|
||||
...
|
||||
Use --force (-f) to move it anyway.
|
||||
```
|
||||
|
||||
Working as intended: a ticket cannot advance while something it waits on is unfinished.
|
||||
Finish the blocker, or use `-f` if the dependency is no longer real. Note that the
|
||||
relation stays on the ticket and will refuse the next move too, and there is no way to
|
||||
take a relation off, so `-f` is the answer every time until the blocker is done.
|
||||
|
||||
If the message says `is blocked by X, which is not on the board`, the blocker has been
|
||||
deleted. That is a warning rather than a refusal and the move goes through.
|
||||
|
||||
### `show` renders `_missing_`
|
||||
|
||||
A relation or a Campaign field naming something the board no longer holds. Harmless to
|
||||
read and impossible to clear, since `relate` only adds and `assign` only moves a ticket
|
||||
between campaigns that exist. For a campaign, `worklane assign <a-real-campaign> <ticket>`
|
||||
overwrites it. For a relation, leave it.
|
||||
|
||||
### A status is missing from `worklane ls`
|
||||
|
||||
The count list at the top of `ls` names every status directory it found, so a status that
|
||||
is absent from it has had its directory deleted. Nothing errors until something tries to
|
||||
move a ticket there, which then fails with a raw file error.
|
||||
|
||||
**File exception.** `worklane init` will not repair it, since it refuses on a board that
|
||||
already exists. Recreate the directory:
|
||||
|
||||
```
|
||||
mkdir .worklane/reviewing
|
||||
```
|
||||
|
||||
### A `.wl-*.tmp` file in `.worklane/`
|
||||
|
||||
The staging file for a write that was killed part way. Every write stages here and renames
|
||||
into place, so a leftover means the write did not finish; nothing reads these and no
|
||||
listing shows them.
|
||||
|
||||
**File exception.** Delete it. Then check the ticket it names with `worklane show` and
|
||||
redo whatever the interrupted command was.
|
||||
|
||||
### Nothing works and the error names `.worklane`
|
||||
|
||||
Check where you are. Commands resolve the nearest `.worklane` at or above the working
|
||||
directory, so running from the wrong directory addresses another board or none. `worklane
|
||||
ls` from where you think the board is, is the fastest way to find out.
|
||||
|
||||
## What this skill does not touch
|
||||
|
||||
- **Priorities, due dates, campaign membership and retagging sweeps.** That is
|
||||
`worklane-plan`. Deciding the vocabulary is here; applying it across the board is there.
|
||||
- **Filing a ticket, working one, moving it through the statuses.** That is the `worklane`
|
||||
skill.
|
||||
- **Judging whether a finished ticket is really done.** That is `worklane-review`.
|
||||
- **The content of a ticket.** A description or an acceptance criterion that is wrong is
|
||||
the author's, and the answer is a comment on that ticket.
|
||||
+19
-1
@@ -136,6 +136,14 @@ field on purpose, which is a different thing from emptying it by forgetting a ta
|
||||
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
||||
replace-the-whole-field rule above.
|
||||
|
||||
**Designing the vocabulary is the `worklane-admin` skill, not this one.** What the tags
|
||||
should be, what each one means, how one is declared with `worklane tags add` and annotated
|
||||
so the next person picks the same word: read that document before proposing a vocabulary,
|
||||
and read `.worklane/tags.md` before proposing a tag. This section is the sweep over
|
||||
tickets already tagged, which is a different job. A board whose tags are declared has an
|
||||
annotation per tag, and a ticket that contradicts one is mis-tagged against a written
|
||||
standard rather than against your reading of the board.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read `worklane tags`, count
|
||||
what is actually used, and show the count before proposing anything. What to report:
|
||||
|
||||
@@ -160,7 +168,8 @@ fields; a goal is a campaign.
|
||||
worklane campaign ls
|
||||
worklane campaign show v1
|
||||
worklane campaign add --title "..." --codename v1 --description "..."
|
||||
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
||||
worklane campaign set v1 --title "..." # or --description or --codename, on one already filed
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24
|
||||
```
|
||||
|
||||
@@ -186,6 +195,12 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
- **Do not propose renaming a codename a campaign already has.** It is what the campaign is
|
||||
called on every card in it and at the command line, so changing it is churn dressed as
|
||||
grooming. `campaign set` refuses it without `--force` for that reason.
|
||||
- **A campaign's description is editable, so a wrong one is a fix rather than a refiling.**
|
||||
A container whose description no longer describes what its members are for is worth
|
||||
pointing out: it is the line every one of those tickets was filed against. `campaign set
|
||||
--description` replaces it and `campaign append --description` adds to it, so neither
|
||||
needs the campaign refiled and its members reassigned. Adding to it is the usual answer;
|
||||
replacing prose to add a sentence to it is how the rest of it gets lost.
|
||||
|
||||
Proposing a campaign means naming the goal, the members, and what is deliberately left
|
||||
out of it. The last part is what makes it a goal rather than a pile.
|
||||
@@ -199,6 +214,9 @@ out of it. The last part is what makes it a goal rather than a pile.
|
||||
columns is reporting progress that did not happen.
|
||||
- **Owner.** `chown` records a commitment a person made. Propose it, do not write it,
|
||||
unless you were asked to assign the work.
|
||||
- **The tag vocabulary itself, and the state of the board's own files.** Declaring a tag,
|
||||
writing what it means, retiring one, or repairing a ticket whose file and fields have
|
||||
come apart: all `worklane-admin`. A sweep applies the vocabulary, it does not decide it.
|
||||
- **New tickets.** Grooming is about what is on the board. Something genuinely missing is
|
||||
worth filing, by the rules in the `worklane` skill, but say it is a new ticket rather
|
||||
than folding it into a grooming sweep.
|
||||
|
||||
+74
-11
@@ -6,10 +6,10 @@ description: Manage tickets on a local worklane kanban board with the `worklane`
|
||||
# worklane
|
||||
|
||||
A kanban board as files. Every ticket is one markdown file in `.worklane/<status>/`,
|
||||
named `<uuid>_<slug>.md`, and comments live in `.worklane/comments/<uuid>/`. The CLI is
|
||||
the only thing that writes there: do not hand-edit or hand-place a file, because the
|
||||
filename, the `Status` field and the directory have to agree and the commands are what
|
||||
keep them agreeing.
|
||||
named `<uuid>_<slug>.md`, and its history lives in `.worklane/history/<uuid>/`, one file
|
||||
per entry. The CLI is the only thing that writes there: do not hand-edit or hand-place a
|
||||
file, because the filename, the `Status` field and the directory have to agree and the
|
||||
commands are what keep them agreeing.
|
||||
|
||||
Commands walk up from the working directory to find the nearest `.worklane`, so **run
|
||||
`worklane` inside the repo the ticket belongs to**. Which directory you run it in is
|
||||
@@ -48,7 +48,7 @@ worklane ls # every status, counts then tickets
|
||||
worklane ls backlog # one status
|
||||
worklane ls --priority 1 # only the most urgent
|
||||
worklane ls --tag bug # only the tickets carrying that tag
|
||||
worklane show 1b78a24 # one ticket, body and comments
|
||||
worklane show 1b78a24 # one ticket, body and history
|
||||
```
|
||||
|
||||
`ls` prints a seven-character id per ticket. That is what you address it by.
|
||||
@@ -211,7 +211,8 @@ worklane campaign add --title "First public release" --codename v1 \
|
||||
worklane campaign ls # every campaign, its codename, how far it has got
|
||||
worklane campaign ls --ids # id and title, tab separated, like ls --ids
|
||||
worklane campaign show v1 # its body, then its members by status
|
||||
worklane campaign set v1 --title "..." # replace the title or the codename
|
||||
worklane campaign set v1 --title "..." # replace the title, description or codename
|
||||
worklane campaign append v1 -d "..." # add a paragraph to the description
|
||||
worklane assign v1 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign v1 # only that campaign's tickets
|
||||
```
|
||||
@@ -226,9 +227,16 @@ existed needs. **Replacing a codename it already has needs `--force`**: that wor
|
||||
the campaign is referred to on the board and at the command line, so changing it is a
|
||||
decision rather than a correction. Setting the one it already has is a no-op either way.
|
||||
|
||||
`campaign set` is the only way to change a campaign after it is filed, and it reaches the
|
||||
title and the codename only. There is no way to edit a campaign's description or its owner
|
||||
yet.
|
||||
`campaign set` and `campaign append` are the only ways to change a campaign after it is
|
||||
filed. `set` replaces the title, the description or the codename; `append` adds a paragraph
|
||||
to the description, which is what to use when the description is right and only incomplete,
|
||||
since replacing prose to add a sentence to it is how the rest of it gets lost. An empty
|
||||
`--description ""` between two values is a paragraph break, exactly as it is for a ticket,
|
||||
and a call whose every value is blank is refused: a campaign's description cannot be
|
||||
emptied. There is still no way to change a campaign's owner.
|
||||
|
||||
`append` here is `campaign append` and not the top-level `append`, which takes a ticket. The
|
||||
two objects are addressed the same way, so the command is what says which one is meant.
|
||||
|
||||
`assign` takes the **campaign first and the ticket second**, like `chown`, and is the
|
||||
only writer of the field. `add` has no `--campaign` and neither has `set`, so membership
|
||||
@@ -262,6 +270,58 @@ existing ticket will have been written from a different angle.
|
||||
- Related but not the same: file it, and record it with `relate <new> --relates-to <old>`
|
||||
rather than only mentioning the id in prose.
|
||||
|
||||
## What the board records about your work
|
||||
|
||||
`show` ends with a HISTORY block: every comment on the ticket and every change to its
|
||||
status, owner or tags, oldest first, each naming who made it. You do not write these by
|
||||
hand. `mv`, `chown` and `set --tags` record themselves, and a call that changes nothing
|
||||
records nothing.
|
||||
|
||||
```
|
||||
HISTORY
|
||||
────────────────────
|
||||
|
||||
status backlog → committed claude (2026-08-24 12:45:00)
|
||||
|
||||
From claude (2026-08-24 13:10:22)
|
||||
The offset was never passed to the widget.
|
||||
|
||||
owner _Not set_ → Ansho Rei claude (2026-08-24 13:11:04)
|
||||
```
|
||||
|
||||
Nothing else is logged: ticking a criterion, and editing the title, description, plan,
|
||||
priority or due date, leave no entry. **When one of those matters, say so in a comment.**
|
||||
An implementation plan rewritten because the first one was wrong is worth a sentence; the
|
||||
edit itself is not recorded and nobody can reconstruct why from the file.
|
||||
|
||||
Read the block before picking a ticket up: it says whether somebody has already had it in
|
||||
`committed` and sent it back, which the current status alone does not.
|
||||
|
||||
## Who your entries are attributed to
|
||||
|
||||
Every comment carries an author, and by default that is the git user of the machine you
|
||||
are running on, which is the human whose checkout it is and not you. Set
|
||||
`WORKLANE_ACTOR` in your own environment and it becomes the author of every entry you
|
||||
write, so a board several agents write to says which of them said what:
|
||||
|
||||
```
|
||||
WORKLANE_ACTOR=claude worklane comment 1b78a24 "The offset was never passed to the widget."
|
||||
```
|
||||
|
||||
Set it once where your session's environment is configured, not on each call: `env` in
|
||||
`~/.claude/settings.json` for Claude Code, and the environment opencode is started with
|
||||
for opencode, since it passes its own environment to the tools it runs. `--actor`
|
||||
overrides it for one call and is spelled the same on every command that writes an entry,
|
||||
`comment`, `mv`, `chown` and `set`. An empty value counts as unset and falls back to the
|
||||
git user, and with nothing at all the author is `unknown`. It is free text, checked
|
||||
against nothing: name yourself something a person reading the board will recognise.
|
||||
|
||||
On `chown`, `--actor` is not the user argument: `worklane chown alice 1b78a24` makes alice
|
||||
the ticket's owner, and `--actor` says who made that change.
|
||||
|
||||
If the variable is not set and you cannot set it, pass `--actor` rather than letting the
|
||||
comment claim to be the user's.
|
||||
|
||||
## Shell completions
|
||||
|
||||
```
|
||||
@@ -292,8 +352,8 @@ the candidates and exits 1 rather than guessing.
|
||||
`--print is supported` is stored, not parsed as a flag. The cost is that a genuinely
|
||||
mistyped flag there lands as content instead of failing, so read back what you wrote
|
||||
with `worklane show`.
|
||||
- `--due`, `--priority`, `--tags`, `--owner` and `--status` do *not* accept one, so a
|
||||
mistyped flag on those is a usage error and nothing is written.
|
||||
- `--due`, `--priority`, `--tags`, `--owner`, `--actor` and `--status` do *not* accept one,
|
||||
so a mistyped flag on those is a usage error and nothing is written.
|
||||
- A ticket argument that starts with a hyphen needs the flags first and a separator:
|
||||
`worklane mv --status committed -- -leading-title`.
|
||||
- A comment body of exactly `--` needs its own separator:
|
||||
@@ -301,4 +361,7 @@ the candidates and exits 1 rather than guessing.
|
||||
- An empty value for a scalar is a usage error, not a way to clear the field: use
|
||||
`--clear`. For a section an empty value is a paragraph break, so it cannot mean empty
|
||||
the section either, and an all-blank one is refused with the `--clear` for it named.
|
||||
- **`comment` has no `--owner`.** Owner is the ticket's assignee, which `chown` writes;
|
||||
the author of a comment is `--actor` or `WORKLANE_ACTOR`. The old spelling is a usage
|
||||
error, not an alias.
|
||||
- Piping is safe: `worklane ls | head -3` exits on the closed pipe instead of panicking.
|
||||
|
||||
+26
-6
@@ -187,7 +187,7 @@ export const ls = tool({
|
||||
|
||||
export const show = tool({
|
||||
description:
|
||||
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and comments.",
|
||||
"Show a complete ticket by UUID or title. Displays title, description, acceptance criteria, implementation plan, metadata, and the history: every comment on it and every change to its status, owner or tags.",
|
||||
args: {
|
||||
id: tool.schema
|
||||
.string()
|
||||
@@ -219,6 +219,10 @@ export const mv = tool({
|
||||
.boolean()
|
||||
.describe("Force move (allows non-sequential moves like done -> backlog). Use with caution.")
|
||||
.optional(),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.ticket) {
|
||||
@@ -229,6 +233,7 @@ export const mv = tool({
|
||||
}
|
||||
const cmd: string[] = ["mv", args.ticket, "--status", args.status];
|
||||
if (args.force) cmd.push("--force");
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(cmd, context);
|
||||
@@ -247,9 +252,9 @@ export const comment = tool({
|
||||
body: tool.schema
|
||||
.string()
|
||||
.describe("Comment body text (required). Supports markdown formatting and multiple paragraphs separated by newlines."),
|
||||
owner: tool.schema
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Comment author. If omitted, defaults to the git user.")
|
||||
.describe("Who the entry is attributed to. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\". Set WORKLANE_ACTOR in the environment opencode is started with rather than passing this on every call.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
@@ -261,7 +266,7 @@ export const comment = tool({
|
||||
}
|
||||
|
||||
const cmd: string[] = ["comment", args.ticket, args.body];
|
||||
if (args.owner) cmd.push("--owner", args.owner);
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(cmd, context);
|
||||
@@ -306,6 +311,10 @@ export const set = tool({
|
||||
.string()
|
||||
.describe("New priority level, 1 (most urgent) to 5 (least)")
|
||||
.optional(),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to. Only reaches the entry tags writes, since that is the one field of this command's that is logged. If omitted, WORKLANE_ACTOR is used, then the git user.")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.ticket) {
|
||||
@@ -330,8 +339,12 @@ export const set = tool({
|
||||
if (args.tags) cmd.push("--tags", args.tags);
|
||||
if (args.due) cmd.push("--due", args.due);
|
||||
if (args.priority) cmd.push("--priority", String(args.priority));
|
||||
// Last, and not counted as a field: the length check below is what refuses a call
|
||||
// that names nothing to change, and an actor alone changes nothing.
|
||||
const fields = cmd.length;
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
if (cmd.length === 2) {
|
||||
if (fields === 2) {
|
||||
return "Error setting fields: give at least one field to change";
|
||||
}
|
||||
|
||||
@@ -405,6 +418,10 @@ export const chown = tool({
|
||||
ticket: tool.schema
|
||||
.string()
|
||||
.describe("Ticket UUID prefix (4+ chars) or title substring (required)"),
|
||||
actor: tool.schema
|
||||
.string()
|
||||
.describe("Who the entry is attributed to, which on this command is not the same as user: user becomes the ticket's owner, actor is who made the change. If omitted, WORKLANE_ACTOR is used, then the git user, then \"unknown\".")
|
||||
.optional(),
|
||||
},
|
||||
async execute(args: Record<string, any>, context: ToolContext) {
|
||||
if (!args.user) {
|
||||
@@ -414,8 +431,11 @@ export const chown = tool({
|
||||
return "Error changing owner: ticket is required";
|
||||
}
|
||||
|
||||
const cmd: string[] = ["chown", args.user, args.ticket];
|
||||
if (args.actor) cmd.push("--actor", args.actor);
|
||||
|
||||
try {
|
||||
return await run(["chown", args.user, args.ticket], context);
|
||||
return await run(cmd, context);
|
||||
} catch (err: any) {
|
||||
return `Error changing owner: ${err.message}`;
|
||||
}
|
||||
|
||||
+5
-5
@@ -173,22 +173,22 @@ impl CampaignIndex {
|
||||
/// target does, rather than as the bare value the file stores: the value is a full
|
||||
/// uuid, so showing it raw is thirty-six characters that say nothing about what is
|
||||
/// gone.
|
||||
pub fn campaign_cell(content: &str, index: &CampaignIndex, colored: bool) -> String {
|
||||
pub fn campaign_cells(content: &str, index: &CampaignIndex) -> Vec<Cell> {
|
||||
let Some(uuid) = parse_campaign(content) else {
|
||||
return String::new();
|
||||
return Vec::new();
|
||||
};
|
||||
|
||||
reference_cell(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()), colored)
|
||||
reference_cells(&uuid, index.get(&uuid).map(|campaign| campaign.title.as_str()))
|
||||
}
|
||||
|
||||
/// The parts [`content_trim`] cannot render from the ticket file alone.
|
||||
///
|
||||
/// Both halves read the tree beside the ticket, so they are gathered in one place
|
||||
/// rather than at each call site.
|
||||
pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result<Resolved> {
|
||||
pub fn resolved_for(content: &str, worklane_dir: &Path) -> Result<Resolved> {
|
||||
Ok(Resolved {
|
||||
relations: relations_for(content, worklane_dir)?,
|
||||
campaign: campaign_cell(content, &CampaignIndex::load(worklane_dir)?, colored),
|
||||
campaign: campaign_cells(content, &CampaignIndex::load(worklane_dir)?),
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
+189
-21
@@ -180,6 +180,12 @@ fn annotation_line(raw: &str) -> Result<String, String> {
|
||||
}
|
||||
}
|
||||
|
||||
/// What `--actor` says on every command that writes a history entry.
|
||||
///
|
||||
/// One string, so the four spell it the same: a flag documented differently on each
|
||||
/// command reads as four flags.
|
||||
const ACTOR_HELP: &str = "Who the entry is attributed to, overriding WORKLANE_ACTOR and the git user. Free text, checked against nothing";
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -221,6 +227,9 @@ pub enum Command {
|
||||
/// Force move (allows backward or non-sequential moves)
|
||||
#[arg(short, long)]
|
||||
force: bool,
|
||||
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
actor: Option<String>,
|
||||
},
|
||||
|
||||
/// Replace fields on an existing ticket
|
||||
@@ -267,9 +276,10 @@ pub enum Command {
|
||||
#[arg(allow_hyphen_values = PROSE)]
|
||||
body: String,
|
||||
|
||||
/// Owner
|
||||
#[arg(short, long)]
|
||||
owner: Option<String>,
|
||||
/// Named after the writer of the entry, not after the ticket's assignee, which
|
||||
/// is `chown`'s. It was `--owner`, which said the wrong one of the two.
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
actor: Option<String>,
|
||||
},
|
||||
|
||||
/// Group tickets that have to be finished together
|
||||
@@ -358,10 +368,18 @@ pub enum Command {
|
||||
/// No `mv`: a campaign has no status to move it to, its state is derived from its
|
||||
/// members.
|
||||
///
|
||||
/// No `append`, and therefore no `set --description`: `set` and `append` are a pair for a
|
||||
/// prose section, and a way to replace a description with no way to add a paragraph to one
|
||||
/// is half of it. That pair is its own ticket. `set` here carries the two scalars, which
|
||||
/// have no append form at all, the same line `append` already draws for a ticket.
|
||||
/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a
|
||||
/// pair: a way to replace a description with no way to add a paragraph to one is the half
|
||||
/// that is easy to reach for and wrong, since replacing a description to add a sentence is
|
||||
/// how the rest of it gets lost. The two scalars have no append form at all, which is the
|
||||
/// same line `append` already draws for a ticket.
|
||||
///
|
||||
/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one
|
||||
/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers
|
||||
/// are the same over both directories, so a search can resolve in each and nothing but a
|
||||
/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which
|
||||
/// explains a ticket search that names a campaign. Under `campaign` the object is settled by
|
||||
/// the command, the way it is for `set`, `show` and `ls`.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum CampaignCommand {
|
||||
/// File a new campaign
|
||||
@@ -369,11 +387,19 @@ pub enum CampaignCommand {
|
||||
|
||||
/// Replace fields on an existing campaign
|
||||
///
|
||||
/// The only way to change a campaign after it is filed. `campaign add --codename` writes
|
||||
/// the field at creation the way `add --title` does for a ticket; this is what replaces
|
||||
/// it, so every campaign filed before the field existed can still be given one.
|
||||
/// The only way to change a campaign's title or codename after it is filed.
|
||||
/// `campaign add --codename` writes the field at creation the way `add --title` does for
|
||||
/// a ticket; this is what replaces it, so every campaign filed before the field existed
|
||||
/// can still be given one.
|
||||
Set(CampaignSetArgs),
|
||||
|
||||
/// Add a paragraph to a campaign's description
|
||||
///
|
||||
/// The other half of `campaign set --description`, and the half that keeps what is
|
||||
/// already written: a description is the sentence a whole campaign's members are filed
|
||||
/// against, so adding a line to it must not mean retyping it.
|
||||
Append(CampaignAppendArgs),
|
||||
|
||||
/// List campaigns with their member counts
|
||||
Ls {
|
||||
/// Print one campaign per line as its id and title, tab separated, for a script
|
||||
@@ -394,25 +420,30 @@ pub enum CampaignCommand {
|
||||
},
|
||||
}
|
||||
|
||||
/// What can be replaced on a campaign that is already filed: its title and its codename.
|
||||
///
|
||||
/// The two scalars, and deliberately not the description. See [`CampaignCommand`].
|
||||
/// What can be replaced on a campaign that is already filed: everything it holds but its
|
||||
/// owner.
|
||||
///
|
||||
/// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle
|
||||
/// by accident whether `chown` grows a campaign or `set` keeps the field, which is the
|
||||
/// one-field-one-writer question and not this command's to answer.
|
||||
///
|
||||
/// No `--clear`: nothing has asked to empty a codename, a wrong one is replaced rather than
|
||||
/// emptied, and the vocabulary is a real question — `Clearable` is `SetArgs`'s and its
|
||||
/// variants are a ticket's fields, so reusing it here would put a ticket's enum on a
|
||||
/// campaign and inventing a second one is a decision worth making on purpose.
|
||||
/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced
|
||||
/// rather than emptied, and a campaign's one prose section has no cleared form worth
|
||||
/// reaching: emptying the description of a container six tickets are filed against is not a
|
||||
/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`]
|
||||
/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one
|
||||
/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it
|
||||
/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go
|
||||
/// back to rather than naming a flag that does not exist.
|
||||
///
|
||||
/// `--force` guards the codename and nothing else. A campaign that already has one is
|
||||
/// referred to by it: it is on every card in the campaign, it is what resolves it at the
|
||||
/// command line, and it is very likely in somebody's shell history. Replacing that silently
|
||||
/// is the same mistake overwriting an edited skill document would be, which is what
|
||||
/// `install-skill --force` exists for. A title needs no guard, since a campaign always has
|
||||
/// one and replacing it is the whole point of the flag.
|
||||
/// one and replacing it is the whole point of the flag. Neither does a description: it is
|
||||
/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a
|
||||
/// guard in front of the command's whole purpose is worse than no command.
|
||||
///
|
||||
/// The group makes at least one field mandatory, so a bare `worklane campaign set <c>` is a
|
||||
/// usage error rather than a silent no-op, exactly as it is for [`SetArgs`].
|
||||
@@ -421,7 +452,7 @@ pub enum CampaignCommand {
|
||||
clap::ArgGroup::new("campaign_set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "codename"])
|
||||
.args(["title", "description", "codename"])
|
||||
))]
|
||||
pub struct CampaignSetArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
@@ -431,6 +462,13 @@ pub struct CampaignSetArgs {
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
|
||||
pub title: Option<String>,
|
||||
|
||||
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
|
||||
///
|
||||
/// The whole section, so a paragraph added to it is `campaign append --description`
|
||||
/// rather than the description retyped
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
|
||||
/// Replace the codename, a single word to call the campaign by
|
||||
///
|
||||
/// The same parser `campaign add --codename` takes, so a codename is one thing however
|
||||
@@ -449,6 +487,25 @@ pub struct CampaignSetArgs {
|
||||
pub force: bool,
|
||||
}
|
||||
|
||||
/// What can be added to a campaign that is already filed: a paragraph of its description.
|
||||
///
|
||||
/// One field, so it is `required` rather than a group of one, which is the longer way to say
|
||||
/// the same thing and the shape [`TagSetArgs`] already takes. A bare
|
||||
/// `worklane campaign append <c>` is therefore a usage error rather than a silent no-op.
|
||||
///
|
||||
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
|
||||
/// the line `append` already draws for a ticket, where the title is absent for the same
|
||||
/// reason.
|
||||
#[derive(clap::Args)]
|
||||
pub struct CampaignAppendArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
pub campaign: String,
|
||||
|
||||
/// Add a paragraph to the description. Repeat the flag for more lines within it
|
||||
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
}
|
||||
|
||||
/// What a campaign holds: a title, a description and an owner.
|
||||
///
|
||||
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
|
||||
@@ -490,13 +547,14 @@ pub struct CampaignAddArgs {
|
||||
/// 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.
|
||||
///
|
||||
/// No `set`: changing an annotation is 9688d34, and a half of `add`/`set` that only ever
|
||||
/// declares is the honest half to ship first.
|
||||
#[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,
|
||||
}
|
||||
@@ -518,6 +576,41 @@ pub struct TagAddArgs {
|
||||
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
|
||||
@@ -645,6 +738,11 @@ pub struct SetArgs {
|
||||
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
|
||||
#[arg(long, value_name = "FIELD")]
|
||||
pub clear: Vec<Clearable>,
|
||||
|
||||
/// Only reaches the entry `--tags` writes, since that is the one field of this
|
||||
/// command's that is logged
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
pub actor: Option<String>,
|
||||
}
|
||||
|
||||
impl SetArgs {
|
||||
@@ -690,6 +788,11 @@ pub struct ChownArgs {
|
||||
/// user to name
|
||||
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
|
||||
pub clear: Option<String>,
|
||||
|
||||
/// Not the same as `user`, which is the ticket's new assignee: this is who made the
|
||||
/// change. Both are on this command because it writes both.
|
||||
#[arg(long, help = ACTOR_HELP)]
|
||||
pub actor: Option<String>,
|
||||
}
|
||||
|
||||
impl ChownArgs {
|
||||
@@ -798,3 +901,68 @@ pub struct CheckArgs {
|
||||
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
|
||||
pub criteria: Vec<String>,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
use clap::CommandFactory;
|
||||
|
||||
/// The command names as the README table would have to spell them: `campaign add`
|
||||
/// for a nested one, the bare name for a top level one. `help` is clap's own and
|
||||
/// documents nothing.
|
||||
fn documented_names() -> Vec<String> {
|
||||
let cli = Cli::command();
|
||||
let mut names = Vec::new();
|
||||
|
||||
for sub in cli.get_subcommands() {
|
||||
if sub.get_name() == "help" {
|
||||
continue;
|
||||
}
|
||||
|
||||
names.push(sub.get_name().to_string());
|
||||
for nested in sub.get_subcommands() {
|
||||
if nested.get_name() == "help" {
|
||||
continue;
|
||||
}
|
||||
|
||||
names.push(format!("{} {}", sub.get_name(), nested.get_name()));
|
||||
}
|
||||
}
|
||||
|
||||
names
|
||||
}
|
||||
|
||||
/// Every subcommand has a row in the README's command table.
|
||||
///
|
||||
/// `campaign` and `assign` went undocumented for two minor versions, e6e3a1b, and
|
||||
/// the `--campaign` flag went with them, because the only thing walking the table
|
||||
/// was somebody remembering to. This is what walks it. A command whose row is
|
||||
/// missing is a command a reader of the README cannot discover at all, which is a
|
||||
/// worse failure than a row that is merely out of date.
|
||||
#[test]
|
||||
fn every_subcommand_has_a_row_in_the_readme_command_table() {
|
||||
// The tag subcommands are f7dd1a1's, which rewrites the `worklane tags` row
|
||||
// once the vocabulary work above it has landed. Listed rather than skipped, so
|
||||
// emptying this is part of closing that ticket rather than something to
|
||||
// rediscover.
|
||||
const PENDING: [&str; 3] = ["tags add", "tags set", "tags ls"];
|
||||
|
||||
let readme = include_str!("../README.md");
|
||||
let table: String = readme.lines().filter(|line| line.starts_with('|')).collect();
|
||||
|
||||
let missing: Vec<String> = documented_names()
|
||||
.into_iter()
|
||||
.filter(|name| !PENDING.contains(&name.as_str()))
|
||||
.filter(|name| !table.contains(&format!("`worklane {}", name)))
|
||||
.collect();
|
||||
|
||||
assert!(
|
||||
missing.is_empty(),
|
||||
"no row in the README command table for {missing:?}. A new command is not \
|
||||
shipped until the table lists it: that table is the only place a reader \
|
||||
discovers one, and two commands hid behind an otherwise complete table \
|
||||
for two minor versions."
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
+77
-15
@@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
|
||||
|
||||
/// Nested subcommands whose first argument is a campaign, as `parent child`.
|
||||
///
|
||||
/// `campaign show` and `campaign set`, and they are why the fish half needs a third
|
||||
/// position helper: their argument is the *third* token, where `__worklane_first_arg_of`
|
||||
/// reads the second and `__worklane_second_arg_of` counts a top-level command's arguments.
|
||||
/// Neither can tell `campaign show <TAB>` from `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 2] = [("campaign", "show"), ("campaign", "set")];
|
||||
/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half
|
||||
/// needs a third position helper: their argument is the *third* token, where
|
||||
/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a
|
||||
/// top-level command's arguments. Neither can tell `campaign show <TAB>` from
|
||||
/// `chown alice <TAB>` by position.
|
||||
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
|
||||
("campaign", "show"),
|
||||
("campaign", "set"),
|
||||
("campaign", "append"),
|
||||
];
|
||||
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
@@ -66,6 +71,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 +106,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
|
||||
@@ -178,9 +197,21 @@ complete -c worklane -n '__worklane_command_is ls' {campaign_flags} \
|
||||
-x -a '(worklane campaign ls --ids)'
|
||||
|
||||
# Tags come from `worklane tags` rather than from a listing of objects, since a tag has no
|
||||
# id. The count after the tab lands as fish's description, which is what makes the list
|
||||
# worth reading: it says which spelling the board actually uses.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} -x -a '(worklane tags)'
|
||||
# id. Three fields now, the tag, its count and its annotation, and fish takes everything
|
||||
# after the *first* tab as one description, so the count is dropped here rather than landing
|
||||
# in the middle of the prose. `cut` and not `string replace` because the columns are what is
|
||||
# being picked, and `cut -f1` is how a script reads this listing anyway.
|
||||
#
|
||||
# What is left is the annotation, and a tag the board carries but has never declared has
|
||||
# none: it is offered with no description at all, which is the near-duplicate the file was
|
||||
# added to catch. The count used to be the description and said the same thing more weakly.
|
||||
complete -c worklane -n '__worklane_command_is ls' {tag_flags} \
|
||||
-x -a '(worklane tags | cut -f1,3)'
|
||||
|
||||
# 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 | cut -f1,3)'
|
||||
|
||||
# `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`
|
||||
@@ -348,7 +379,10 @@ mod tests {
|
||||
|
||||
// A guard on the walker itself: if it stopped finding arguments, every assertion
|
||||
// above would pass by never running.
|
||||
assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign");
|
||||
assert_eq!(
|
||||
seen, 5,
|
||||
"expected assign, campaign show, campaign set, campaign append and ls --campaign"
|
||||
);
|
||||
}
|
||||
|
||||
/// Commands whose tag positional names a tag that does not exist yet.
|
||||
@@ -377,16 +411,18 @@ mod tests {
|
||||
let name = path.join(" ");
|
||||
|
||||
let Some(long) = arg.get_long() else {
|
||||
let nested = match path.as_slice() {
|
||||
let known = match path.as_slice() {
|
||||
[parent, child] => {
|
||||
TAG_NEW_COMMANDS.contains(&(parent.as_str(), child.as_str()))
|
||||
let pair = (parent.as_str(), child.as_str());
|
||||
TAG_NESTED_COMMANDS.contains(&pair) || TAG_NEW_COMMANDS.contains(&pair)
|
||||
}
|
||||
_ => false,
|
||||
};
|
||||
assert!(
|
||||
nested,
|
||||
"`worklane {name}` takes a tag as a positional, \
|
||||
which the fish block has no rule for"
|
||||
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;
|
||||
};
|
||||
@@ -397,7 +433,7 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 2, "expected ls --tag and tags add");
|
||||
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
|
||||
@@ -493,6 +529,32 @@ mod tests {
|
||||
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
|
||||
}
|
||||
|
||||
/// Every rule that reads the tag listing drops the count, because `worklane tags` prints
|
||||
/// three fields and fish takes everything after the first tab as the description. Left
|
||||
/// whole, a tag would be described as its count, a tab and its annotation.
|
||||
///
|
||||
/// Pinned per rule rather than once over the script: a rule added later that reads
|
||||
/// `worklane tags` raw is the bug this catches, and it would not show up in a single
|
||||
/// `contains`.
|
||||
#[test]
|
||||
fn every_tag_rule_takes_the_annotation_as_its_description() {
|
||||
let script = fish_dynamic();
|
||||
|
||||
let reading: Vec<&str> = script
|
||||
.lines()
|
||||
.filter(|line| line.contains("(worklane tags"))
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
reading.len(),
|
||||
2,
|
||||
"expected the ls --tag rule and the tags set one: {reading:?}"
|
||||
);
|
||||
for line in reading {
|
||||
assert!(line.contains("(worklane tags | cut -f1,3)"), "{line}");
|
||||
}
|
||||
}
|
||||
|
||||
/// The one status positional and the one shell positional, which clap does not emit
|
||||
/// possible values for. Read off the enums, so a fifth status would appear here on
|
||||
/// its own.
|
||||
|
||||
+245
-176
@@ -7,9 +7,10 @@ use std::path::Path;
|
||||
|
||||
use crate::campaign::*;
|
||||
use crate::command::{
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
|
||||
RelateArgs, SetArgs, TagAddArgs,
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs,
|
||||
ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs,
|
||||
};
|
||||
use crate::history::{Kind, change, format_history, read_history, write_entry};
|
||||
use crate::install;
|
||||
use crate::tag::{TAGS_FILE, TagIndex, tags_path};
|
||||
use crate::util::*;
|
||||
@@ -351,99 +352,12 @@ pub fn cmd_add(args: &AddArgs, start: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Public for the TUI's detail view, which shows the same comments `show` does.
|
||||
pub fn read_comments(comments_dir: &Path) -> Result<Vec<(String, String, String, String)>> {
|
||||
if !comments_dir.exists() {
|
||||
return Ok(vec![]);
|
||||
}
|
||||
|
||||
let mut comments: Vec<(String, String, String, String)> = Vec::new();
|
||||
|
||||
for entry in fs::read_dir(comments_dir)? {
|
||||
let entry = entry?;
|
||||
let path = entry.path();
|
||||
if path.extension().is_some_and(|e| e == "md") {
|
||||
let content = fs::read_to_string(&path)?;
|
||||
let filename = path
|
||||
.file_stem()
|
||||
.map(|s| s.to_string_lossy().to_string())
|
||||
.unwrap_or_default();
|
||||
|
||||
let author = content
|
||||
.lines()
|
||||
.find(|l| l.starts_with("**Author**"))
|
||||
.and_then(|l| l.split_once("**Author**:"))
|
||||
.map(|(_, value)| value)
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
let time = content
|
||||
.lines()
|
||||
.find(|l| l.starts_with("**Time**"))
|
||||
.and_then(|l| l.split_once("**Time**:"))
|
||||
.map(|(_, value)| value)
|
||||
.map(|s| s.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string());
|
||||
|
||||
let body = if let Some(after_comment) = content.strip_prefix("**Comment**\n") {
|
||||
if let Some(end) = after_comment.find("\n\n**Author**") {
|
||||
after_comment[..end].trim()
|
||||
} else {
|
||||
after_comment.trim()
|
||||
}
|
||||
} else {
|
||||
""
|
||||
};
|
||||
|
||||
comments.push((filename, author, time, body.to_string()));
|
||||
}
|
||||
}
|
||||
|
||||
comments.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
|
||||
Ok(comments)
|
||||
}
|
||||
|
||||
/// Write a comment under the first free name derived from `stem`.
|
||||
///
|
||||
/// `create_new` rather than `fs::write`: a name that already exists means another
|
||||
/// comment landed in the same microsecond, and truncating it is exactly the data
|
||||
/// loss this guards against. The suffix is zero padded so the names keep sorting
|
||||
/// in the order they were written.
|
||||
fn write_new_comment(comments_dir: &Path, stem: &str, content: &str) -> Result<String> {
|
||||
for attempt in 0..100 {
|
||||
let filename = match attempt {
|
||||
0 => format!("{}.md", stem),
|
||||
n => format!("{}_{:02}.md", stem, n),
|
||||
};
|
||||
|
||||
match fs::OpenOptions::new()
|
||||
.write(true)
|
||||
.create_new(true)
|
||||
.open(comments_dir.join(&filename))
|
||||
{
|
||||
Ok(mut file) => {
|
||||
file.write_all(content.as_bytes())?;
|
||||
return Ok(filename);
|
||||
}
|
||||
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
|
||||
Err(e) => return Err(e.into()),
|
||||
}
|
||||
}
|
||||
|
||||
Err(anyhow!(
|
||||
"No free comment filename for '{}' in {}",
|
||||
stem,
|
||||
comments_dir.display()
|
||||
))
|
||||
}
|
||||
|
||||
pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
let (_status, title, content) = resolve_ticket(search, worklane_dir)?;
|
||||
let ticket_uuid = parse_ticket_field(&content, "ID");
|
||||
// Read before anything is printed, so a board that cannot be read fails instead of
|
||||
// half printing a ticket.
|
||||
let resolved = resolved_for(&content, worklane_dir, should_use_colors())?;
|
||||
let resolved = resolved_for(&content, worklane_dir)?;
|
||||
|
||||
// The only title in the output: content_trim_colored used to print it a second
|
||||
// time from the file content. Green per the colour guideline, and the rule is
|
||||
@@ -453,9 +367,8 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
println!("\n{}", content_trim_colored(&content, &resolved));
|
||||
|
||||
if ticket_uuid != "_Not set_" {
|
||||
let comments_dir = comments_dir(worklane_dir, &ticket_uuid);
|
||||
let comments = read_comments(&comments_dir)?;
|
||||
let formatted = format_comments(&comments);
|
||||
let entries = read_history(worklane_dir, &ticket_uuid)?;
|
||||
let formatted = format_history(&entries);
|
||||
println!("{}", formatted);
|
||||
}
|
||||
|
||||
@@ -642,7 +555,13 @@ fn check_blockers(worklane_dir: &Path, content: &str, title: &str) -> Result<()>
|
||||
/// A status is a [`Status`] rather than a string, so an unknown one is clap's to refuse
|
||||
/// and nothing here has to check. What is left is the order of the flow, which is
|
||||
/// `Status::ALL`.
|
||||
pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Result<()> {
|
||||
pub fn cmd_mv(
|
||||
ticket_id: &str,
|
||||
target: Status,
|
||||
force: bool,
|
||||
actor: &Option<String>,
|
||||
start: &Path,
|
||||
) -> Result<()> {
|
||||
let target_status = target.as_str();
|
||||
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
@@ -712,6 +631,17 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
&title,
|
||||
)?;
|
||||
|
||||
// After the move, never before: an entry for a move that was refused would be a log
|
||||
// of things that did not happen. The no-op above returns without one for the same
|
||||
// reason.
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&parse_ticket_field(&resolved, "ID"),
|
||||
Kind::Status,
|
||||
&change(¤t_status, target_status),
|
||||
&resolve_actor(actor.as_deref()),
|
||||
)?;
|
||||
|
||||
println!(
|
||||
"Moved ticket '{}' from {} to {}",
|
||||
color_text(&title, Color::Green),
|
||||
@@ -725,7 +655,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
pub fn cmd_comment(
|
||||
ticket_id: &str,
|
||||
body: &str,
|
||||
owner: &Option<String>,
|
||||
actor: &Option<String>,
|
||||
start: &Path,
|
||||
) -> Result<()> {
|
||||
if body.is_empty() {
|
||||
@@ -740,29 +670,13 @@ pub fn cmd_comment(
|
||||
return Err(anyhow!("Could not determine ticket ID."));
|
||||
}
|
||||
|
||||
let comments_dir = comments_dir(&worklane_dir, &ticket_uuid);
|
||||
fs::create_dir_all(&comments_dir)?;
|
||||
|
||||
let stem = Local::now().format(COMMENT_FILE_FORMAT).to_string();
|
||||
|
||||
let author = match owner {
|
||||
Some(o) => o.clone(),
|
||||
None => get_git_user().unwrap_or_else(|| "unknown".to_string()),
|
||||
};
|
||||
|
||||
let comment_content = format!(
|
||||
"**Comment**\n\
|
||||
{}\n\
|
||||
\n\
|
||||
**Author**: {}\n\
|
||||
**Time**: {}\n\
|
||||
",
|
||||
let filename = write_entry(
|
||||
&worklane_dir,
|
||||
&ticket_uuid,
|
||||
Kind::Comment,
|
||||
body,
|
||||
author,
|
||||
Local::now().format(TIMESTAMP_FORMAT)
|
||||
);
|
||||
|
||||
let filename = write_new_comment(&comments_dir, &stem, &comment_content)?;
|
||||
&resolve_actor(actor.as_deref()),
|
||||
)?;
|
||||
|
||||
println!("Comment added to '{}' ({})", title, filename);
|
||||
Ok(())
|
||||
@@ -784,6 +698,42 @@ fn section_args<'a>(
|
||||
]
|
||||
}
|
||||
|
||||
/// The lines a caller's values amount to, or the refusal an all-blank call earns.
|
||||
///
|
||||
/// An empty value is a paragraph break, so a call whose values are *every one* blank asked
|
||||
/// for nothing, and writing an empty section is not what it meant. Shared by `set` and
|
||||
/// `campaign set` because the rule is the section's rather than the object's.
|
||||
///
|
||||
/// `instead` is the way out, and it is the caller's because the callers differ: a ticket's
|
||||
/// section is emptied with `--clear <field>`, and a campaign's description has no cleared
|
||||
/// form at all, per [`CampaignSetArgs`].
|
||||
fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: {}",
|
||||
section.label,
|
||||
instead
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// The same for `append`, which has no way out to name: appending nothing was never a way
|
||||
/// to empty anything, so the message says only that there was nothing to add.
|
||||
fn appended_items(section: &Section, values: &[String]) -> Result<Vec<String>> {
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// Write the ticket back, renaming the file when a new title changes its slug.
|
||||
///
|
||||
/// The content goes down first and the rename second, the same order and for the same
|
||||
@@ -872,12 +822,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<()> {
|
||||
@@ -906,14 +867,8 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"An empty value is a paragraph break, not a way to empty the {}: use --clear {}",
|
||||
section.label,
|
||||
section.clear.map_or("", Clearable::name)
|
||||
));
|
||||
}
|
||||
let clear = format!("use --clear {}", section.clear.map_or("", Clearable::name));
|
||||
let items = replaced_items(section, values, &clear)?;
|
||||
|
||||
let next = set_section_body(&content, section, &items)?;
|
||||
apply(&mut content, &mut changed, section.label, next);
|
||||
@@ -955,6 +910,23 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> {
|
||||
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, renamed, &content)?;
|
||||
|
||||
// Tags alone, of everything `set` writes. The other fields change often enough that a
|
||||
// log of them is noise, and `apply` is what decides this: a field it did not record as
|
||||
// changed was already what the call asked for. Emptying the field counts, since
|
||||
// `--clear tags` is the same field going somewhere.
|
||||
if changed.contains(&"tags") || cleared.contains(&"tags") {
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Tags,
|
||||
&change(
|
||||
&parse_ticket_field(&original, "Tags"),
|
||||
&parse_ticket_field(&content, "Tags"),
|
||||
),
|
||||
&resolve_actor(args.actor.as_deref()),
|
||||
)?;
|
||||
}
|
||||
|
||||
let shown = args.title.clone().unwrap_or(title);
|
||||
if !changed.is_empty() {
|
||||
report(&changed, &shown, "Updated");
|
||||
@@ -999,6 +971,19 @@ pub fn cmd_chown(args: &ChownArgs, start: &Path) -> Result<()> {
|
||||
|
||||
save_ticket(&worklane_dir, &status, &uuid, &title, None, &content)?;
|
||||
|
||||
// Behind the no-change return above, so a chown to the owner a ticket already has
|
||||
// records nothing, and after the save, so a failed write logs nothing.
|
||||
write_entry(
|
||||
&worklane_dir,
|
||||
&uuid,
|
||||
Kind::Owner,
|
||||
&change(
|
||||
&parse_ticket_field(&original, "Owner"),
|
||||
&parse_ticket_field(&content, "Owner"),
|
||||
),
|
||||
&resolve_actor(args.actor.as_deref()),
|
||||
)?;
|
||||
|
||||
let verb = match user {
|
||||
Some(_) => "Updated",
|
||||
None => "Cleared",
|
||||
@@ -1020,13 +1005,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> {
|
||||
continue;
|
||||
}
|
||||
|
||||
let items = section.normalise(values);
|
||||
if items.is_empty() {
|
||||
return Err(anyhow!(
|
||||
"Nothing to append to the {}: every value given was blank",
|
||||
section.label
|
||||
));
|
||||
}
|
||||
let items = appended_items(section, values)?;
|
||||
|
||||
content = append_section_body(&content, section, &items)?;
|
||||
changed.push(section.label);
|
||||
@@ -1206,27 +1185,52 @@ pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Every tag on the board, with how many tickets carry it.
|
||||
/// Every tag on the board: the ones the tickets carry, the ones the file declares, and
|
||||
/// what each declared one means.
|
||||
///
|
||||
/// The vocabulary itself, which nothing else could answer: `ls --tag` filters by a tag
|
||||
/// already known, and the decorated listing does not print tags at all. A grooming sweep
|
||||
/// starts by asking what the vocabulary *is*, and `assets/PLAN.md` used to have to say
|
||||
/// that the question could only be answered by reading the tickets.
|
||||
///
|
||||
/// **The union of the two vocabularies, not either one.** Since `tags.md` exists there are
|
||||
/// two: the tags the file declares and the tags the tickets carry. A declared tag nothing
|
||||
/// carries lists at zero rather than being dropped, and a carried tag nothing declares
|
||||
/// still lists. Those two cases are the whole reason to declare tags at all, so this is
|
||||
/// the command that has to show them apart.
|
||||
///
|
||||
/// **Alphabetical, and case sensitive.** `--tag` matches a whole value case sensitively,
|
||||
/// so `bug` and `Bug` are two tags and listing them as one would hide the reason a filter
|
||||
/// came back short. Sorting puts them next to each other, which is where a near-duplicate
|
||||
/// is spotted.
|
||||
///
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count.
|
||||
/// Fish reads what follows the tab as a description, a script takes `cut -f1`, and neither
|
||||
/// wants an escape sequence. Every status, done included, for the reason `ls --ids`
|
||||
/// includes it: a tag retired months ago is still part of the answer to what the
|
||||
/// vocabulary has been.
|
||||
/// Machine-readable, the second output in the tree that is: the tag, a tab, the count, and
|
||||
/// a tab and the annotation's opening line for a tag the file declares. Fish reads what
|
||||
/// follows the first tab as a description, a script takes `cut -f1`, and neither wants an
|
||||
/// escape sequence.
|
||||
///
|
||||
/// **A carried but undeclared tag is marked by the absence of the third field**, which is
|
||||
/// where the shape comes from. Anything appended to the tag itself would have a completion
|
||||
/// offer a tag that does not exist, and anything added to the count would stop the second
|
||||
/// field being a number. Absence costs neither, and it buys the one property a marker
|
||||
/// could not: a board with no `tags.md` has every tag undeclared, so it prints two fields
|
||||
/// a line, which is byte for byte what this printed before the file existed. The shipped
|
||||
/// fish completion of an older version is still reading that.
|
||||
///
|
||||
/// Every status, done included, for the reason `ls --ids` includes it: a tag retired months
|
||||
/// ago is still part of the answer to what the vocabulary has been.
|
||||
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
// Through the same `load` `tags add` uses, so a file that is there and cannot be read
|
||||
// is an error here too. The listing is the one tag command that could go on without the
|
||||
// file, and reporting a vocabulary while silently treating a broken file as no file is
|
||||
// the wrong half of the answer.
|
||||
let index = TagIndex::load(worklane_dir)?;
|
||||
|
||||
// BTreeMap rather than a sort afterwards: the order is the point, and the counting
|
||||
// wants a map anyway.
|
||||
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
|
||||
// wants a map anyway. Seeded from the vocabulary rather than merged into afterwards,
|
||||
// which is what puts a declared tag nothing carries in at zero.
|
||||
let mut counts: BTreeMap<String, usize> =
|
||||
index.names().map(|tag| (tag.to_string(), 0)).collect();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
@@ -1242,7 +1246,10 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
}
|
||||
|
||||
for (tag, count) in counts {
|
||||
println!("{}\t{}", tag, count);
|
||||
match index.summary(&tag) {
|
||||
Some(summary) => println!("{tag}\t{count}\t{summary}"),
|
||||
None => println!("{tag}\t{count}"),
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
@@ -1296,6 +1303,53 @@ pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
|
||||
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,
|
||||
@@ -1323,6 +1377,18 @@ pub fn cmd_tag_add(args: &TagAddArgs, start: &Path) -> Result<()> {
|
||||
/// No-op detection compares the whole file, the way `set` and `chown` do, so setting a
|
||||
/// codename a campaign already carries writes nothing. That is a no-op and not a refusal:
|
||||
/// `--force` is about overwriting a *different* word, and there is nothing to overwrite.
|
||||
///
|
||||
/// **The description goes through `set_section_body` and the `DESCRIPTION` entry**, the
|
||||
/// section table `cmd_set` and `campaign_body` already read, so what a campaign's one prose
|
||||
/// section *is* stays decided in one place. A second definition scoped to campaigns would
|
||||
/// drift on the spelling of the heading, which is the drift `campaign_body` was written
|
||||
/// against.
|
||||
///
|
||||
/// A campaign whose Description heading is gone is refused by that call rather than given
|
||||
/// the section back through `ensure_section`. Every campaign the tool has ever filed carries
|
||||
/// the heading, so an insertion path here would be reachable only from a hand-edited file:
|
||||
/// that is the opposite of the Relations case, where `add` writes nothing and the insertion
|
||||
/// is the only path there is.
|
||||
pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
@@ -1350,6 +1416,16 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
apply(&mut content, &mut changed, "title", next);
|
||||
}
|
||||
|
||||
if !args.description.is_empty() {
|
||||
let items = replaced_items(
|
||||
&DESCRIPTION,
|
||||
&args.description,
|
||||
"a campaign's description has no cleared form",
|
||||
)?;
|
||||
let next = set_section_body(&content, &DESCRIPTION, &items)?;
|
||||
apply(&mut content, &mut changed, DESCRIPTION.label, next);
|
||||
}
|
||||
|
||||
if let Some(codename) = &args.codename {
|
||||
let next = set_or_insert_metadata_field(&content, CODENAME_FIELD, codename, &title)?;
|
||||
apply(&mut content, &mut changed, "codename", next);
|
||||
@@ -1367,6 +1443,32 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Add a paragraph to a campaign's description.
|
||||
///
|
||||
/// The other half of `campaign set --description`, and `cmd_append` for a campaign: the same
|
||||
/// `append_section_body` and the same `DESCRIPTION` entry, so a paragraph lands under a
|
||||
/// campaign's description the way it lands under a ticket's, blank line and all. A campaign
|
||||
/// filed with no description holds the placeholder, and that is replaced rather than
|
||||
/// followed, which is `append_section_body`'s rule and not a case handled here.
|
||||
///
|
||||
/// No whole-file comparison, unlike `set`: every value blank is refused above, so there is
|
||||
/// nothing left that appends nothing. `cmd_append` says it the same way.
|
||||
///
|
||||
/// One section, so there is no loop and no list to report: what changed is the description
|
||||
/// or the call failed.
|
||||
pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let campaign = resolve_campaign(&args.campaign, &worklane_dir)?;
|
||||
|
||||
let items = appended_items(&DESCRIPTION, &args.description)?;
|
||||
let content = append_section_body(&campaign.content, &DESCRIPTION, &items)?;
|
||||
|
||||
save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?;
|
||||
|
||||
report(&[DESCRIPTION.label], &campaign.title, "Appended to");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Show a campaign, then its members grouped by status.
|
||||
///
|
||||
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
|
||||
@@ -1699,36 +1801,3 @@ pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
/// The collision path cannot be provoked from the CLI, since two processes
|
||||
/// will not share a microsecond, but it is the whole point of the guard.
|
||||
#[test]
|
||||
fn a_colliding_stem_takes_the_next_name_and_keeps_the_first() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-test-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
let first = write_new_comment(&dir, "20260820_143012_123456", "first").unwrap();
|
||||
let second = write_new_comment(&dir, "20260820_143012_123456", "second").unwrap();
|
||||
let third = write_new_comment(&dir, "20260820_143012_123456", "third").unwrap();
|
||||
|
||||
assert_eq!(first, "20260820_143012_123456.md");
|
||||
assert_eq!(second, "20260820_143012_123456_01.md");
|
||||
assert_eq!(third, "20260820_143012_123456_02.md");
|
||||
|
||||
// Nothing was truncated on the way through
|
||||
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
|
||||
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
|
||||
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
|
||||
|
||||
// read_comments sorts on the stem, so the names must sort in write order
|
||||
let mut names = vec![second.clone(), third.clone(), first.clone()];
|
||||
names.sort();
|
||||
assert_eq!(names, vec![first, second, third]);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
+642
@@ -0,0 +1,642 @@
|
||||
//! What happened to a ticket, one file per entry.
|
||||
//!
|
||||
//! The comments directory was already an append-only log with exactly one event kind:
|
||||
//! one file per entry under a directory named by the ticket's uuid, stamped to the
|
||||
//! microsecond and written with `create_new` so two writers cannot clobber each other.
|
||||
//! This is that log with the kind named in it, so a status change, an owner change and a
|
||||
//! tag change are recorded beside what somebody said about them.
|
||||
//!
|
||||
//! What is deliberately not logged: ticking or unticking a criterion, and edits to the
|
||||
//! title, description, plan, priority or due. Those change often and a log of them is
|
||||
//! noise. When one of them matters, whoever made it adds a comment saying why, which is
|
||||
//! the record actually worth keeping.
|
||||
//!
|
||||
//! Every entry names its author, from [`resolve_actor`], so a board several agents write
|
||||
//! to says which of them did what.
|
||||
//!
|
||||
//! [`resolve_actor`]: crate::util::resolve_actor
|
||||
|
||||
use std::fs;
|
||||
use std::io::Write;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Result, anyhow};
|
||||
use chrono::Local;
|
||||
|
||||
use crate::util::{Cell, Color, TIMESTAMP_FORMAT, paint_cells, should_use_colors};
|
||||
|
||||
/// Where a ticket's history lives, under the board.
|
||||
///
|
||||
/// Beside the status directories rather than among them, the way `campaigns_dir` is: an
|
||||
/// entry has no status of its own. Spelled once here, so the writer, the reader and the
|
||||
/// card's counter cannot disagree about the path.
|
||||
pub const HISTORY_DIR: &str = "history";
|
||||
|
||||
/// The name the same directory had while a comment was the only entry it could hold.
|
||||
///
|
||||
/// Kept so a board written by an older version is adopted rather than migrated by hand.
|
||||
/// See [`adopt_comments`].
|
||||
pub const COMMENTS_DIR: &str = "comments";
|
||||
|
||||
/// How an entry filename is stamped.
|
||||
///
|
||||
/// Microseconds, not seconds: at second resolution two entries in the same second
|
||||
/// produced the same name and the second silently truncated the first. Fixed width and
|
||||
/// first in the name, so the lexicographic sort in [`read_history`] stays chronological
|
||||
/// whatever kind follows it.
|
||||
pub const ENTRY_FILE_FORMAT: &str = "%Y%m%d_%H%M%S_%6f";
|
||||
|
||||
/// The history root of a board.
|
||||
pub fn history_root(board: &Path) -> PathBuf {
|
||||
board.join(HISTORY_DIR)
|
||||
}
|
||||
|
||||
/// The history directory for one ticket, named by its full uuid.
|
||||
pub fn history_dir(board: &Path, uuid: &str) -> PathBuf {
|
||||
history_root(board).join(uuid)
|
||||
}
|
||||
|
||||
/// What an entry records.
|
||||
///
|
||||
/// An enum rather than a string, so a kind the reader does not know is a compile error
|
||||
/// instead of a word that renders as itself. The variants are the four things worth
|
||||
/// keeping: what somebody said, and the three fields whose history answers a question.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum Kind {
|
||||
Comment,
|
||||
Status,
|
||||
Owner,
|
||||
Tags,
|
||||
}
|
||||
|
||||
impl Kind {
|
||||
/// Every kind, which is what the reader matches a marker against and what the
|
||||
/// counter matches a filename against.
|
||||
pub const ALL: [Kind; 4] = [Kind::Comment, Kind::Status, Kind::Owner, Kind::Tags];
|
||||
|
||||
/// The width the mechanical labels are padded to, `status` being the longest of the
|
||||
/// three. `comment` is longer and is not padded to: a comment renders as a header
|
||||
/// and a body, not as a row.
|
||||
const LABEL_WIDTH: usize = 6;
|
||||
|
||||
/// The word in the filename, and the label a mechanical entry renders under.
|
||||
pub fn slug(self) -> &'static str {
|
||||
match self {
|
||||
Kind::Comment => "comment",
|
||||
Kind::Status => "status",
|
||||
Kind::Owner => "owner",
|
||||
Kind::Tags => "tags",
|
||||
}
|
||||
}
|
||||
|
||||
/// The marker the file opens with, which is what the reader keys the kind off.
|
||||
///
|
||||
/// The file is the record and the filename is an index into it: a name can be
|
||||
/// changed by anything that touches the directory, so the kind is read from the
|
||||
/// content and only counted from the name.
|
||||
fn marker(self) -> &'static str {
|
||||
match self {
|
||||
Kind::Comment => "**Comment**",
|
||||
Kind::Status => "**Status**",
|
||||
Kind::Owner => "**Owner**",
|
||||
Kind::Tags => "**Tags**",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// One entry: what happened, who wrote it and when.
|
||||
#[derive(Debug)]
|
||||
pub struct Entry {
|
||||
/// The file stem, which is what the entries are sorted by.
|
||||
pub filename: String,
|
||||
pub kind: Kind,
|
||||
pub author: String,
|
||||
pub time: String,
|
||||
/// A comment's text, or the before and after of the field a mechanical entry names.
|
||||
pub body: String,
|
||||
}
|
||||
|
||||
/// Rename an old `comments` directory to `history`, before anything reads or writes it.
|
||||
///
|
||||
/// One rename rather than a migration command: the entries themselves need no rewriting,
|
||||
/// since [`parse_entry`] reads a file with no marker as the comment it is. Called by the
|
||||
/// reader, the writer and the counter, so no caller has to remember it and a board can
|
||||
/// never be reached through a path that skips it.
|
||||
///
|
||||
/// Both directories at once is refused rather than merged. Only the CLI writes there, so
|
||||
/// it cannot arrive at that state on its own, and choosing which of two entries with the
|
||||
/// same name survives is not a decision to make silently.
|
||||
pub fn adopt_comments(board: &Path) -> Result<()> {
|
||||
let old = board.join(COMMENTS_DIR);
|
||||
if !old.exists() {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let new = history_root(board);
|
||||
if new.exists() {
|
||||
return Err(anyhow!(
|
||||
"Board holds both {} and {}. Only worklane writes there, so this needs a \
|
||||
person: move the entries under {} into the matching directories in {}, \
|
||||
then remove it.",
|
||||
old.display(),
|
||||
new.display(),
|
||||
COMMENTS_DIR,
|
||||
HISTORY_DIR,
|
||||
));
|
||||
}
|
||||
|
||||
fs::rename(&old, &new)
|
||||
.map_err(|e| anyhow!("Could not rename {} to {}: {}", old.display(), new.display(), e))
|
||||
}
|
||||
|
||||
/// One entry, from its filename and its content.
|
||||
///
|
||||
/// Split out from the directory walk so the parse can be tested without a fixture, and
|
||||
/// because it is where the compatibility lives: a file with no marker is a comment,
|
||||
/// which is what every entry written before the kinds existed is.
|
||||
fn parse_entry(filename: &str, content: &str) -> Entry {
|
||||
let field = |name: &str| {
|
||||
let marker = format!("**{}**:", name);
|
||||
content
|
||||
.lines()
|
||||
.find(|line| line.starts_with(&marker))
|
||||
.and_then(|line| line.split_once(&marker))
|
||||
.map(|(_, value)| value.trim().to_string())
|
||||
.unwrap_or_else(|| "unknown".to_string())
|
||||
};
|
||||
|
||||
let kind = Kind::ALL
|
||||
.into_iter()
|
||||
.find(|kind| content.starts_with(&format!("{}\n", kind.marker())))
|
||||
.unwrap_or(Kind::Comment);
|
||||
|
||||
let body = content
|
||||
.strip_prefix(&format!("{}\n", kind.marker()))
|
||||
.map(|rest| match rest.find("\n\n**Author**") {
|
||||
Some(end) => rest[..end].trim(),
|
||||
None => rest.trim(),
|
||||
})
|
||||
.unwrap_or("");
|
||||
|
||||
Entry {
|
||||
filename: filename.to_string(),
|
||||
kind,
|
||||
author: field("Author"),
|
||||
time: field("Time"),
|
||||
body: body.to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Every entry on a ticket, oldest first.
|
||||
///
|
||||
/// Public for the TUI's detail view, which shows the same sequence `show` does.
|
||||
pub fn read_history(board: &Path, uuid: &str) -> Result<Vec<Entry>> {
|
||||
adopt_comments(board)?;
|
||||
|
||||
let dir = history_dir(board, uuid);
|
||||
if !dir.exists() {
|
||||
return Ok(vec![]);
|
||||
}
|
||||
|
||||
let mut entries: Vec<Entry> = Vec::new();
|
||||
|
||||
for entry in fs::read_dir(&dir)? {
|
||||
let path = entry?.path();
|
||||
if path.extension().is_some_and(|ext| ext == "md") {
|
||||
let content = fs::read_to_string(&path)?;
|
||||
let filename = path
|
||||
.file_stem()
|
||||
.map(|stem| stem.to_string_lossy().to_string())
|
||||
.unwrap_or_default();
|
||||
entries.push(parse_entry(&filename, &content));
|
||||
}
|
||||
}
|
||||
|
||||
// The stamp is fixed width and leads the name, so this is chronological.
|
||||
entries.sort_by(|a, b| a.filename.cmp(&b.filename));
|
||||
|
||||
Ok(entries)
|
||||
}
|
||||
|
||||
/// The kind a filename names, which is what the count reads instead of the file.
|
||||
///
|
||||
/// A stem with no kind in it is a comment, the same compatibility [`parse_entry`] has.
|
||||
/// The collision suffix is a number and matches no slug, so it is skipped.
|
||||
fn kind_from_stem(stem: &str) -> Kind {
|
||||
stem.split('_')
|
||||
.find_map(|part| Kind::ALL.into_iter().find(|kind| kind.slug() == part))
|
||||
.unwrap_or(Kind::Comment)
|
||||
}
|
||||
|
||||
/// How many comments a ticket carries, counted off the directory rather than read.
|
||||
///
|
||||
/// Comments only, so the card's counter still says how many things somebody said: a
|
||||
/// ticket that has moved three times has not been talked about. `.md` only, the filter
|
||||
/// [`read_history`] applies, so a stray file dropped in there is not counted. A missing
|
||||
/// directory is none, which is what a ticket nothing has happened to has.
|
||||
pub fn count_comments(board: &Path, uuid: &str) -> usize {
|
||||
// Swallowed, unlike the reader's: a count is drawn on every card and a board that
|
||||
// cannot be adopted has to draw as the zero it looks like rather than take the TUI
|
||||
// down. The next write reports the real reason.
|
||||
let _ = adopt_comments(board);
|
||||
|
||||
let Ok(entries) = fs::read_dir(history_dir(board, uuid)) else {
|
||||
return 0;
|
||||
};
|
||||
|
||||
entries
|
||||
.filter_map(|entry| entry.ok())
|
||||
.filter(|entry| entry.path().extension().is_some_and(|ext| ext == "md"))
|
||||
.filter(|entry| {
|
||||
let stem = entry.path().file_stem().map(|s| s.to_string_lossy().to_string());
|
||||
stem.is_some_and(|stem| kind_from_stem(&stem) == Kind::Comment)
|
||||
})
|
||||
.count()
|
||||
}
|
||||
|
||||
/// The file an entry is written as.
|
||||
///
|
||||
/// A comment's file is byte for byte what `comment` wrote before the kinds existed, so
|
||||
/// nothing has to be rewritten and a board can be read by either version.
|
||||
fn entry_content(kind: Kind, body: &str, author: &str, time: &str) -> String {
|
||||
format!(
|
||||
"{}\n\
|
||||
{}\n\
|
||||
\n\
|
||||
**Author**: {}\n\
|
||||
**Time**: {}\n\
|
||||
",
|
||||
kind.marker(),
|
||||
body,
|
||||
author,
|
||||
time
|
||||
)
|
||||
}
|
||||
|
||||
/// Write an entry under the first free name derived from the stamp.
|
||||
///
|
||||
/// `create_new` rather than `fs::write`: a name that already exists means another entry
|
||||
/// landed in the same microsecond, and truncating it is exactly the data loss this
|
||||
/// guards against. The suffix is zero padded so the names keep sorting in the order they
|
||||
/// were written.
|
||||
fn write_new(dir: &Path, stem: &str, content: &str) -> Result<String> {
|
||||
for attempt in 0..100 {
|
||||
let filename = match attempt {
|
||||
0 => format!("{}.md", stem),
|
||||
n => format!("{}_{:02}.md", stem, n),
|
||||
};
|
||||
|
||||
match fs::OpenOptions::new()
|
||||
.write(true)
|
||||
.create_new(true)
|
||||
.open(dir.join(&filename))
|
||||
{
|
||||
Ok(mut file) => {
|
||||
file.write_all(content.as_bytes())?;
|
||||
return Ok(filename);
|
||||
}
|
||||
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
|
||||
Err(e) => return Err(e.into()),
|
||||
}
|
||||
}
|
||||
|
||||
Err(anyhow!("No free entry filename for '{}' in {}", stem, dir.display()))
|
||||
}
|
||||
|
||||
/// Record one entry on a ticket, returning the filename it landed under.
|
||||
///
|
||||
/// Called after the edit it describes has been written, never before: an entry for a
|
||||
/// move that was refused would be a log of things that did not happen. The cost of that
|
||||
/// order is that a failed write here leaves the edit in place and reports the failure,
|
||||
/// which is the right way round — the ticket is the record and this is the story of it.
|
||||
pub fn write_entry(
|
||||
board: &Path,
|
||||
uuid: &str,
|
||||
kind: Kind,
|
||||
body: &str,
|
||||
author: &str,
|
||||
) -> Result<String> {
|
||||
adopt_comments(board)?;
|
||||
|
||||
let dir = history_dir(board, uuid);
|
||||
fs::create_dir_all(&dir)?;
|
||||
|
||||
let now = Local::now();
|
||||
let stem = format!("{}_{}", now.format(ENTRY_FILE_FORMAT), kind.slug());
|
||||
let content = entry_content(kind, body, author, &now.format(TIMESTAMP_FORMAT).to_string());
|
||||
|
||||
write_new(&dir, &stem, &content)
|
||||
}
|
||||
|
||||
/// What a mechanical entry records: the field before the edit and after it.
|
||||
///
|
||||
/// The values as the ticket holds them, sentinels included, so `_Not set_` reads the way
|
||||
/// the field it came from does rather than being translated into a word this module
|
||||
/// invented.
|
||||
pub fn change(before: &str, after: &str) -> String {
|
||||
format!("{} → {}", before, after)
|
||||
}
|
||||
|
||||
pub fn format_history(entries: &[Entry]) -> String {
|
||||
format_history_with(entries, should_use_colors())
|
||||
}
|
||||
|
||||
/// As above, with the colour decision passed in.
|
||||
pub fn format_history_with(entries: &[Entry], colored: bool) -> String {
|
||||
paint_cells(&history_cells(entries), colored)
|
||||
}
|
||||
|
||||
/// The block laid out once, as [`Cell`]s: the CLI paints them and the board turns the
|
||||
/// same ones into styled spans, so the two views cannot draw two different blocks.
|
||||
pub fn history_cells(entries: &[Entry]) -> Vec<Cell> {
|
||||
if entries.is_empty() {
|
||||
return vec![Cell::colored("No history yet.", Color::Grey)];
|
||||
}
|
||||
|
||||
let mut cells = Vec::new();
|
||||
cells.push(Cell::plain("\n"));
|
||||
cells.push(Cell::colored("HISTORY", Color::Orange));
|
||||
cells.push(Cell::plain(format!("\n{}\n", "─".repeat(20))));
|
||||
|
||||
for entry in entries {
|
||||
cells.push(Cell::plain("\n"));
|
||||
let stamp = format!("{} ({})", entry.author, entry.time);
|
||||
|
||||
match entry.kind {
|
||||
// As it has always read: a header naming who said it, then the text.
|
||||
Kind::Comment => {
|
||||
cells.push(Cell::colored(format!("From {}", stamp), Color::Cyan));
|
||||
cells.push(Cell::plain("\n"));
|
||||
if !entry.body.is_empty() {
|
||||
cells.push(Cell::plain(format!(" {}", entry.body)));
|
||||
}
|
||||
cells.push(Cell::plain("\n"));
|
||||
}
|
||||
// One line: a field change is one fact and a paragraph for it would bury the
|
||||
// comments it sits between.
|
||||
_ => {
|
||||
let padding = Kind::LABEL_WIDTH.saturating_sub(entry.kind.slug().chars().count());
|
||||
cells.push(Cell::colored(entry.kind.slug(), Color::Orange));
|
||||
cells.push(Cell::plain(format!("{} ", " ".repeat(padding))));
|
||||
cells.push(Cell::plain(entry.body.clone()));
|
||||
cells.push(Cell::plain(" "));
|
||||
cells.push(Cell::colored(stamp, Color::Cyan));
|
||||
cells.push(Cell::plain("\n"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cells
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::util::{Fixture, paint};
|
||||
|
||||
fn board() -> Fixture {
|
||||
Fixture::new("worklane-history")
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_entry_names_its_kind_in_the_file_and_in_the_filename() {
|
||||
let board = board();
|
||||
let filename =
|
||||
write_entry(&board, "uuid", Kind::Status, "committed → reviewing", "claude").unwrap();
|
||||
|
||||
assert!(filename.ends_with("_status.md"), "was {filename}");
|
||||
|
||||
let entries = read_history(&board, "uuid").unwrap();
|
||||
assert_eq!(entries.len(), 1);
|
||||
assert_eq!(entries[0].kind, Kind::Status);
|
||||
assert_eq!(entries[0].body, "committed → reviewing");
|
||||
assert_eq!(entries[0].author, "claude");
|
||||
}
|
||||
|
||||
/// The stamp leads the name and is fixed width, so the kind that follows it cannot
|
||||
/// reorder the log.
|
||||
#[test]
|
||||
fn the_kind_in_the_name_does_not_disturb_the_order() {
|
||||
let mut names = [
|
||||
"20260824_120000_000000_status",
|
||||
"20260824_115959_999999_tags",
|
||||
"20260824_120000_000001_comment",
|
||||
];
|
||||
names.sort();
|
||||
assert_eq!(
|
||||
names,
|
||||
[
|
||||
"20260824_115959_999999_tags",
|
||||
"20260824_120000_000000_status",
|
||||
"20260824_120000_000001_comment",
|
||||
]
|
||||
);
|
||||
}
|
||||
|
||||
/// A file written before the kinds existed: no marker, so it is the comment it was,
|
||||
/// and nothing rewrites it.
|
||||
#[test]
|
||||
fn an_entry_with_no_marker_is_a_comment() {
|
||||
let legacy = parse_entry(
|
||||
"20260820_143012_123456",
|
||||
"**Comment**\nSomething said\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
|
||||
);
|
||||
assert_eq!(legacy.kind, Kind::Comment);
|
||||
assert_eq!(legacy.body, "Something said");
|
||||
assert_eq!(legacy.author, "Ansho Rei");
|
||||
|
||||
// And one with no marker at all, which is what `read_comments` read as empty.
|
||||
let bare = parse_entry("20260820_143012_123457", "notes\n");
|
||||
assert_eq!(bare.kind, Kind::Comment);
|
||||
assert_eq!(bare.body, "");
|
||||
}
|
||||
|
||||
/// The comment file is byte for byte what `comment` wrote before this module, which
|
||||
/// is what lets an old board be read without a migration.
|
||||
#[test]
|
||||
fn a_comment_file_is_shaped_as_it_always_was() {
|
||||
let content = entry_content(Kind::Comment, "A body", "claude", "2026-08-24 12:00:00");
|
||||
assert_eq!(
|
||||
content,
|
||||
"**Comment**\nA body\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
|
||||
);
|
||||
}
|
||||
|
||||
/// Same microsecond, three entries: the guard is `create_new`, and the suffix keeps
|
||||
/// them in the order they were written.
|
||||
#[test]
|
||||
fn entries_in_one_microsecond_get_names_of_their_own() {
|
||||
let board = board();
|
||||
let dir = history_dir(&board, "uuid");
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
let first = write_new(&dir, "20260820_143012_123456_comment", "first").unwrap();
|
||||
let second = write_new(&dir, "20260820_143012_123456_comment", "second").unwrap();
|
||||
let third = write_new(&dir, "20260820_143012_123456_comment", "third").unwrap();
|
||||
|
||||
assert_eq!(first, "20260820_143012_123456_comment.md");
|
||||
assert_eq!(second, "20260820_143012_123456_comment_01.md");
|
||||
assert_eq!(third, "20260820_143012_123456_comment_02.md");
|
||||
|
||||
// Nothing was truncated on the way through
|
||||
assert_eq!(fs::read_to_string(dir.join(&first)).unwrap(), "first");
|
||||
assert_eq!(fs::read_to_string(dir.join(&second)).unwrap(), "second");
|
||||
assert_eq!(fs::read_to_string(dir.join(&third)).unwrap(), "third");
|
||||
|
||||
// read_history sorts on the stem, so the names must sort in write order
|
||||
assert!(first < second && second < third, "the names lost their order");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_old_comments_directory_is_adopted_on_access() {
|
||||
let board = board();
|
||||
let comments = board.join(COMMENTS_DIR).join("uuid");
|
||||
fs::create_dir_all(&comments).unwrap();
|
||||
fs::write(
|
||||
comments.join("20260820_143012_123456.md"),
|
||||
"**Comment**\nOld news\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let entries = read_history(&board, "uuid").unwrap();
|
||||
assert_eq!(entries.len(), 1);
|
||||
assert_eq!(entries[0].body, "Old news");
|
||||
|
||||
assert!(!board.join(COMMENTS_DIR).exists(), "the old directory survived");
|
||||
assert!(history_dir(&board, "uuid").exists(), "the entries did not arrive");
|
||||
}
|
||||
|
||||
/// Refused rather than merged: only the CLI writes there, so this is a board somebody
|
||||
/// has been in by hand, and picking a survivor per name is not a silent decision.
|
||||
#[test]
|
||||
fn a_board_holding_both_directories_is_refused() {
|
||||
let board = board();
|
||||
fs::create_dir_all(board.join(COMMENTS_DIR).join("uuid")).unwrap();
|
||||
fs::create_dir_all(history_dir(&board, "uuid")).unwrap();
|
||||
|
||||
let refused = read_history(&board, "uuid");
|
||||
let message = refused.unwrap_err().to_string();
|
||||
assert!(
|
||||
message.contains(COMMENTS_DIR) && message.contains(HISTORY_DIR),
|
||||
"{message}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The count is the card's, and a card counts what somebody said.
|
||||
#[test]
|
||||
fn only_comments_are_counted() {
|
||||
let board = board();
|
||||
write_entry(&board, "uuid", Kind::Comment, "said", "claude").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Status, "backlog → committed", "claude").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Owner, "_Not set_ → alice", "claude").unwrap();
|
||||
write_entry(&board, "uuid", Kind::Tags, "bug → bug, cli", "claude").unwrap();
|
||||
|
||||
assert_eq!(read_history(&board, "uuid").unwrap().len(), 4);
|
||||
assert_eq!(count_comments(&board, "uuid"), 1);
|
||||
}
|
||||
|
||||
/// A stem written before the kinds existed counts as the comment it is.
|
||||
#[test]
|
||||
fn a_legacy_name_counts_as_a_comment() {
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456"), Kind::Comment);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_01"), Kind::Comment);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_status"), Kind::Status);
|
||||
assert_eq!(kind_from_stem("20260820_143012_123456_status_01"), Kind::Status);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_mechanical_entry_renders_as_one_line_and_a_comment_as_it_did() {
|
||||
let entries = vec![
|
||||
parse_entry(
|
||||
"20260824_120000_000000_status",
|
||||
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120001_000000_comment",
|
||||
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
|
||||
),
|
||||
];
|
||||
|
||||
let rendered = format_history_with(&entries, false);
|
||||
assert!(rendered.contains("HISTORY"), "{rendered}");
|
||||
assert!(
|
||||
rendered.contains("status committed → reviewing claude (2026-08-24 12:00:00)\n"),
|
||||
"{rendered}"
|
||||
);
|
||||
assert!(
|
||||
rendered
|
||||
.contains("From Ansho Rei (2026-08-24 12:00:01)\n The offset was never passed"),
|
||||
"{rendered}"
|
||||
);
|
||||
assert!(!rendered.contains('\x1b'), "colour off still painted: {rendered:?}");
|
||||
}
|
||||
|
||||
/// The pin for the cells conversion: `show` prints the block exactly as it printed
|
||||
/// it before, every painted run spelled out, the way
|
||||
/// `show_prints_the_same_body_it_printed_before_the_cells_conversion` pins the body.
|
||||
#[test]
|
||||
fn show_prints_the_same_history_it_printed_before_the_cells_conversion() {
|
||||
let entries = vec![
|
||||
parse_entry(
|
||||
"20260824_120000_000000_status",
|
||||
"**Status**\ncommitted → reviewing\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n",
|
||||
),
|
||||
parse_entry(
|
||||
"20260824_120001_000000_comment",
|
||||
"**Comment**\nThe offset was never passed\n\n**Author**: Ansho Rei\n**Time**: 2026-08-24 12:00:01\n",
|
||||
),
|
||||
];
|
||||
|
||||
let expected = format!(
|
||||
"\n{}\n{}\n\n{} committed → reviewing {}\n\n{}\n The offset was never passed\n",
|
||||
paint("HISTORY", Color::Orange, true),
|
||||
"─".repeat(20),
|
||||
paint("status", Color::Orange, true),
|
||||
paint("claude (2026-08-24 12:00:00)", Color::Cyan, true),
|
||||
paint("From Ansho Rei (2026-08-24 12:00:01)", Color::Cyan, true),
|
||||
);
|
||||
|
||||
assert_eq!(format_history_with(&entries, true), expected);
|
||||
assert_eq!(format_history_with(&[], true), paint("No history yet.", Color::Grey, true));
|
||||
}
|
||||
|
||||
/// Padded to the longest of the three, so every body starts in the same column
|
||||
/// however short the label above it is.
|
||||
#[test]
|
||||
fn the_mechanical_labels_are_aligned() {
|
||||
let bodies = [
|
||||
("status", "backlog → committed"),
|
||||
("owner", "_Not set_ → alice"),
|
||||
("tags", "bug → bug, cli"),
|
||||
];
|
||||
let entries: Vec<Entry> = bodies
|
||||
.into_iter()
|
||||
.map(|(kind, body)| {
|
||||
let marker = format!("**{}{}**", kind[..1].to_uppercase(), &kind[1..]);
|
||||
parse_entry(
|
||||
&format!("20260824_120000_000000_{kind}"),
|
||||
&format!(
|
||||
"{marker}\n{body}\n\n**Author**: claude\n**Time**: 2026-08-24 12:00:00\n"
|
||||
),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
|
||||
let rendered = format_history_with(&entries, false);
|
||||
let columns: Vec<usize> = bodies
|
||||
.into_iter()
|
||||
.map(|(_, body)| rendered.find(body).expect("body missing"))
|
||||
.map(|at| {
|
||||
let line_start = rendered[..at].rfind('\n').map_or(0, |nl| nl + 1);
|
||||
at - line_start
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(columns.len(), 3);
|
||||
assert!(columns.windows(2).all(|pair| pair[0] == pair[1]), "{rendered}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn nothing_recorded_says_so() {
|
||||
assert_eq!(format_history_with(&[], false), "No history yet.");
|
||||
}
|
||||
}
|
||||
+47
-1
@@ -69,11 +69,29 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
content: include_str!("../assets/PLAN.md"),
|
||||
};
|
||||
|
||||
/// The skill that sets a board up and puts one back together.
|
||||
///
|
||||
/// Its own document for the reason the two above are, and the split against `PLAN_SKILL`
|
||||
/// is the one worth stating: that document grooms the *work*, priorities and dates and
|
||||
/// campaigns, and this one configures the *board*, the tag vocabulary and the faults a
|
||||
/// board can develop. The tag section is where they meet, so each points at the other.
|
||||
///
|
||||
/// The one document that has to hold for a board that tracks no software at all. The other
|
||||
/// three describe a workflow that happens to be this repo's; a vocabulary skill written
|
||||
/// around `bug` and `cli` would teach nothing to a board tracking a household, so the
|
||||
/// examples in it deliberately span three subjects.
|
||||
pub const ADMIN_SKILL: Asset = Asset {
|
||||
name: "worklane-admin",
|
||||
what: "skill",
|
||||
relative: "worklane-admin/SKILL.md",
|
||||
content: include_str!("../assets/ADMIN.md"),
|
||||
};
|
||||
|
||||
/// Every skill this binary carries, in the order they install.
|
||||
///
|
||||
/// A `static` rather than a `const` so the slice borrowed from it outlives the
|
||||
/// 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];
|
||||
pub static SKILLS: [Asset; 4] = [SKILL, REVIEW_SKILL, PLAN_SKILL, ADMIN_SKILL];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
@@ -466,6 +484,34 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// What makes the admin document usable on a board that tracks no software, and what
|
||||
/// keeps its repairs honest.
|
||||
///
|
||||
/// The domain examples are the first thing an edit would quietly drop, since every
|
||||
/// other skill here is written around this repo, and dropping them leaves a document
|
||||
/// that teaches a household board to file `cli` tickets. The two-step repair is the
|
||||
/// second: it looks like a typo until you have watched `mv` refuse the one-step
|
||||
/// version, which is why the ticket for this skill demanded every repair be run rather
|
||||
/// than reasoned about.
|
||||
#[test]
|
||||
fn the_admin_skill_stays_domain_neutral_and_keeps_its_verified_repairs() {
|
||||
for required in [
|
||||
"household", // the vocabulary section spans three subjects
|
||||
"product strategy", //
|
||||
"worklane tags add", // the vocabulary is declared through the CLI
|
||||
"--tags` replaces the whole field", // the destructive one, restated where it bites
|
||||
"two moves, not one", // the repair `mv` cannot do in one step
|
||||
"do not edit a ticket file",
|
||||
"File exception", // and the three places that rule does not reach
|
||||
"worklane-plan", // the boundary against the sweep document
|
||||
] {
|
||||
assert!(
|
||||
ADMIN_SKILL.content.contains(required),
|
||||
"the admin skill no longer says {required:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// The decisions that make the review document a review rather than a rewrite.
|
||||
///
|
||||
/// Each of these is a rule an edit would drop without breaking anything else: a
|
||||
|
||||
+24
-8
@@ -6,6 +6,7 @@ mod clipboard;
|
||||
mod command;
|
||||
mod completions;
|
||||
mod handlers;
|
||||
mod history;
|
||||
mod install;
|
||||
mod tag;
|
||||
mod tui;
|
||||
@@ -56,15 +57,17 @@ fn main() -> Result<()> {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_show(&id, &worklane_dir)
|
||||
}
|
||||
Some(Command::Mv { ticket, status, force }) => cmd_mv(&ticket, status, force, &start),
|
||||
Some(Command::Mv { ticket, status, force, actor }) => {
|
||||
cmd_mv(&ticket, status, force, &actor, &start)
|
||||
}
|
||||
Some(Command::Set(args)) => cmd_set(&args, &start),
|
||||
Some(Command::Append(args)) => cmd_append(&args, &start),
|
||||
Some(Command::Relate(args)) => cmd_relate(&args, &start),
|
||||
Some(Command::Chown(args)) => cmd_chown(&args, &start),
|
||||
Some(Command::Check(args)) => cmd_check(&args, true, &start),
|
||||
Some(Command::Uncheck(args)) => cmd_check(&args, false, &start),
|
||||
Some(Command::Comment { ticket, body, owner }) => {
|
||||
cmd_comment(&ticket, &body, &owner, &start)
|
||||
Some(Command::Comment { ticket, body, actor }) => {
|
||||
cmd_comment(&ticket, &body, &actor, &start)
|
||||
}
|
||||
Some(Command::Campaign { command }) => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
|
||||
@@ -73,6 +76,7 @@ fn main() -> Result<()> {
|
||||
cmd_campaign_ls(&worklane_dir, ids)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
|
||||
CampaignCommand::Append(args) => cmd_campaign_append(&args, &start),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_show(&campaign, &worklane_dir)
|
||||
@@ -88,6 +92,7 @@ fn main() -> Result<()> {
|
||||
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.
|
||||
@@ -209,16 +214,23 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
|
||||
board.should_quit = true
|
||||
}
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_detail(),
|
||||
// The frame's own height while it holds the selection, and the detail
|
||||
// overlay on a card. `Board::toggle_focused` rather than a condition here,
|
||||
// for the reason the scroll keys route there.
|
||||
KeyCode::Enter | KeyCode::Char(' ') => board.toggle_focused(screen),
|
||||
KeyCode::Left | KeyCode::Char('h') => board.select_column(-1, screen),
|
||||
KeyCode::Right | KeyCode::Char('l') => board.select_column(1, screen),
|
||||
// Up and down stay on the selection, open detail view or not, so a
|
||||
// column can be read through without closing the modal. Scrolling the
|
||||
// open ticket is a page at a time.
|
||||
// open ticket is a page at a time, and so is scrolling the campaign
|
||||
// frame that up reaches from the top card of a column.
|
||||
KeyCode::Up | KeyCode::Char('k') => board.select_card(-1, screen),
|
||||
KeyCode::Down | KeyCode::Char('j') => board.select_card(1, screen),
|
||||
KeyCode::PageUp => board.scroll_detail(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_detail(1, screen),
|
||||
// The open ticket first and the campaign frame behind it, which is
|
||||
// `Board::scroll_page` rather than a condition written here: the arms in
|
||||
// this dispatch are not reachable from a test.
|
||||
KeyCode::PageUp => board.scroll_page(-1, screen),
|
||||
KeyCode::PageDown => board.scroll_page(1, screen),
|
||||
// Tabs cycle rather than clamp, the way tabs everywhere do, and are
|
||||
// a no-op with a single board. Free of every other binding: the
|
||||
// columns took hjkl and the arrows.
|
||||
@@ -239,7 +251,11 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
// The way in to the campaign picker, like `/` is to the search prompt: from
|
||||
// the next keypress on `picker_key` above has the keyboard. Free of every
|
||||
// other binding, and `ctrl-c` is matched above this so quitting still wins.
|
||||
KeyCode::Char('c') => board.open_picker(),
|
||||
KeyCode::Char('c') => board.open_picker(tui::PickerKind::Campaign, screen),
|
||||
// The other axis the board is cut along, and the one `ls --tag` has
|
||||
// answered since 2f3796e. Free of every other binding: `tab` is its own
|
||||
// key code, not this letter.
|
||||
KeyCode::Char('t') => board.open_picker(tui::PickerKind::Tag, screen),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
+49
@@ -153,6 +153,55 @@ impl TagIndex {
|
||||
self.tags.contains_key(tag)
|
||||
}
|
||||
|
||||
/// Every tag the file declares, alphabetical, whatever the board carries.
|
||||
///
|
||||
/// The half of the listing the status directories cannot answer. A tag declared and
|
||||
/// never applied is carried by no ticket, so counting alone drops it, and that tag is
|
||||
/// most of the reason the file exists: a word the board agreed on and nobody has
|
||||
/// reached for yet is exactly what a grooming sweep wants to see.
|
||||
pub fn names(&self) -> impl Iterator<Item = &str> {
|
||||
self.tags.keys().map(String::as_str)
|
||||
}
|
||||
|
||||
/// What a tag means, whole, or `None` for a tag the file does not declare.
|
||||
///
|
||||
/// The raw section, paragraphs and all, where [`Self::summary`] is the one line a
|
||||
/// listing has room for. `Some("")` is a tag declared with nothing said about it, which
|
||||
/// the caller has to tell apart from `None`: the board draws the two in different
|
||||
/// sections.
|
||||
pub fn annotation(&self, tag: &str) -> Option<&str> {
|
||||
self.tags.get(tag).map(String::as_str)
|
||||
}
|
||||
|
||||
/// The opening line of what a tag means, or `None` for a tag the file does not declare.
|
||||
///
|
||||
/// The cut to one line lives here rather than on the parse, the way
|
||||
/// [`CampaignRow::summary`] takes one line off a description the read carries whole:
|
||||
/// the annotation is prose with paragraphs in it, and which view wants how much of it
|
||||
/// is the view's business.
|
||||
///
|
||||
/// **`None` is what marks a carried but undeclared tag**, since `cmd_tags` prints no
|
||||
/// third field for it. Nothing is appended to the tag itself and nothing is added to
|
||||
/// the count, so `cut -f1` still yields the tag values and a board with no file at all
|
||||
/// lists what it listed before the file existed.
|
||||
///
|
||||
/// A declared tag with nothing said about it answers [`NO_ANNOTATION`] rather than an
|
||||
/// empty string, because an empty third field is a trailing tab and nothing else: it
|
||||
/// would be the only difference between declared and not, and it would be invisible in
|
||||
/// a terminal and in a completion alike. The placeholder is also what the file itself
|
||||
/// holds under that heading, so the field stays the section's opening line either way.
|
||||
///
|
||||
/// [`CampaignRow::summary`]: crate::tui::CampaignRow::summary
|
||||
/// [`NO_ANNOTATION`]: crate::tag::NO_ANNOTATION
|
||||
pub fn summary(&self, tag: &str) -> Option<&str> {
|
||||
let annotation = self.tags.get(tag)?;
|
||||
|
||||
Some(match annotation.lines().next() {
|
||||
Some(line) => line,
|
||||
None => NO_ANNOTATION,
|
||||
})
|
||||
}
|
||||
|
||||
/// Declare `tag`, or replace what it means.
|
||||
///
|
||||
/// One writer for both, because the file holds one section per tag either way and the
|
||||
|
||||
+2534
-361
File diff suppressed because it is too large
Load Diff
+750
-262
File diff suppressed because it is too large
Load Diff
+445
-5
@@ -1129,11 +1129,13 @@ fn an_unknown_campaign_is_refused_and_nothing_is_written() {
|
||||
);
|
||||
}
|
||||
|
||||
/// No `--description`: `set` and `append` are a pair for a prose section, and a way to
|
||||
/// replace a description with no way to add a paragraph is half of it. Pinned so the
|
||||
/// omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
/// `--description` arrived with `campaign append`, 32e98ab, because for a prose section the
|
||||
/// two are a pair. What is still deliberately absent is what this pins: no `--owner`, which
|
||||
/// would settle by accident whether `chown` grows a campaign, and no `--clear`, because a
|
||||
/// campaign's description has no cleared form and `Clearable`'s variants are a ticket's
|
||||
/// fields.
|
||||
#[test]
|
||||
fn campaign_set_offers_no_description_and_no_owner() {
|
||||
fn campaign_set_offers_no_owner_and_no_clear() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
@@ -1142,7 +1144,7 @@ fn campaign_set_offers_no_description_and_no_owner() {
|
||||
|
||||
assert!(help.contains("--codename"), "{help}");
|
||||
assert!(help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--description"), "{help}");
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--owner"), "{help}");
|
||||
assert!(!help.contains("--clear"), "{help}");
|
||||
}
|
||||
@@ -1263,3 +1265,441 @@ fn the_title_is_replaced_without_force() {
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
|
||||
}
|
||||
|
||||
// ---------------------------------------------- campaign set --description --
|
||||
|
||||
/// The point of 32e98ab: the description a campaign was filed with is no longer the one it
|
||||
/// keeps. `create_campaign` writes prose, so this is a replacement rather than a first line.
|
||||
#[test]
|
||||
fn campaign_set_replaces_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"--description",
|
||||
"What the tag has to hold.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Updated description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(
|
||||
!content.contains("What has to ship together."),
|
||||
"the old description survived: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// An empty value between two others is the paragraph break, the rule every prose argument
|
||||
/// in the tool follows: `add --description`, `set --description` and `tags --annotation`.
|
||||
#[test]
|
||||
fn an_empty_value_is_a_paragraph_break_in_a_campaigns_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"The tag itself.",
|
||||
"-d",
|
||||
"",
|
||||
"-d",
|
||||
"And what blocks it.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("The tag itself.\n\nAnd what blocks it."), "{content}");
|
||||
}
|
||||
|
||||
/// And an all-blank value is refused rather than emptying the section. The refusal names no
|
||||
/// flag, because there is none: a campaign's description has no cleared form, which is the
|
||||
/// `Clearable` question 32e98ab settled rather than deferred.
|
||||
#[test]
|
||||
fn an_all_blank_description_is_refused_and_names_no_clear_flag() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "-d", "", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("An empty value is a paragraph break"), "{said}");
|
||||
assert!(said.contains("no cleared form"), "{said}");
|
||||
assert!(!said.contains("--clear"), "it named a flag that does not exist: {said}");
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// The whole-file comparison `set`, `chown` and the codename already use, so a description
|
||||
/// replaced with the one it already holds writes nothing.
|
||||
#[test]
|
||||
fn setting_the_description_a_campaign_already_has_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"What has to ship together.",
|
||||
],
|
||||
);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was rewritten");
|
||||
}
|
||||
|
||||
/// Three fields in one call, since the group is `multiple` and the description is in it.
|
||||
#[test]
|
||||
fn campaign_set_takes_the_title_the_description_and_the_codename_together() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"-t",
|
||||
"First public release",
|
||||
"-d",
|
||||
"What the tag has to hold.",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("title, description, codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
assert!(content.contains("What the tag has to hold."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
}
|
||||
|
||||
/// A refused codename takes the description down with it, the way it already takes the
|
||||
/// title: checked before any edit is applied, so a call writes all of what it asked for or
|
||||
/// none of it.
|
||||
#[test]
|
||||
fn a_refused_codename_takes_the_description_down_with_it() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1",
|
||||
"-d",
|
||||
"Rewritten anyway.",
|
||||
"-c",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the description went through");
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------- campaign append --
|
||||
|
||||
/// The other half of the pair, and the reason `set --description` is not a flag on its own:
|
||||
/// adding a line to a description must not mean retyping the rest of it.
|
||||
#[test]
|
||||
fn campaign_append_adds_a_paragraph_without_replacing_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"And what is out of scope.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Appended to description"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
// The paragraph lands after the one that was there, with the blank line between them
|
||||
// that makes it a paragraph rather than a run-on.
|
||||
assert!(
|
||||
content.contains("What has to ship together.\n\nAnd what is out of scope.\n"),
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Several values in one call are lines *within* the paragraph, not several paragraphs. The
|
||||
/// same reading `append --description` gives a ticket, since it is the same section entry.
|
||||
#[test]
|
||||
fn the_values_of_one_append_are_lines_within_the_paragraph() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"v1 release",
|
||||
"-d",
|
||||
"Out of scope:",
|
||||
"-d",
|
||||
"the installer.",
|
||||
],
|
||||
);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("Out of scope:\nthe installer.\n"), "{content}");
|
||||
}
|
||||
|
||||
/// A campaign filed with no description holds the placeholder, and appending replaces it
|
||||
/// rather than following it: the alternative reads `_No description provided._` above the
|
||||
/// description. `append_section_body`'s rule, so nothing here handles the case.
|
||||
#[test]
|
||||
fn appending_to_an_empty_description_replaces_the_placeholder() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "add", "--title", "No prose yet"]);
|
||||
|
||||
let uuid = {
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_no-prose-yet.md"))
|
||||
.expect("the campaign was not filed");
|
||||
name.split('_').next().unwrap().to_string()
|
||||
};
|
||||
assert!(
|
||||
campaign_file(&worklane, &uuid).contains("_No description provided._"),
|
||||
"the placeholder is not what add writes any more"
|
||||
);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"append",
|
||||
"No prose yet",
|
||||
"-d",
|
||||
"The first thing said.",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let content = campaign_file(&worklane, &uuid);
|
||||
assert!(content.contains("The first thing said."), "{content}");
|
||||
assert!(
|
||||
!content.contains("_No description provided._"),
|
||||
"the placeholder is still above the description: {content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Every value blank is refused rather than writing nothing quietly, the answer `append`
|
||||
/// gives a ticket, in the same words: appending nothing was never a way to empty anything,
|
||||
/// so there is no flag to name.
|
||||
#[test]
|
||||
fn an_all_blank_append_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release", "-d", " "]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("Nothing to append"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written");
|
||||
}
|
||||
|
||||
/// A bare `campaign append <campaign>` is a usage error rather than a silent no-op, the way
|
||||
/// a bare `campaign set` is. `--description` is `required` rather than a group of one.
|
||||
#[test]
|
||||
fn campaign_append_with_no_description_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "v1 release"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
/// Appending to a scalar has no meaning, which is the line `append` already draws for a
|
||||
/// ticket: no `--title` there and none here, and no `--codename` either.
|
||||
#[test]
|
||||
fn campaign_append_offers_only_the_description() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "--help"]);
|
||||
let help = stdout(&out);
|
||||
|
||||
assert!(help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--codename"), "{help}");
|
||||
assert!(!help.contains("--force"), "{help}");
|
||||
}
|
||||
|
||||
/// A campaign is addressed here by the same tiers everything else takes, codename included,
|
||||
/// because it goes through `resolve_campaign` rather than a lookup of its own.
|
||||
#[test]
|
||||
fn campaign_append_resolves_the_campaign_by_its_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "beaver", "-d", "One more thing."]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
campaign_file(&worklane, CAMP_A).contains("One more thing."),
|
||||
"{}",
|
||||
campaign_file(&worklane, CAMP_A)
|
||||
);
|
||||
}
|
||||
|
||||
/// An unknown campaign leaves every campaign alone, the answer `campaign set` and `assign`
|
||||
/// already give.
|
||||
#[test]
|
||||
fn campaign_append_refuses_an_unknown_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let before = campaign_file(&worklane, CAMP_A);
|
||||
|
||||
let out = run(&temp, &["campaign", "append", "nothing-by-that-name", "-d", "Text."]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written");
|
||||
}
|
||||
|
||||
// ------------------------------------------------------ the shared machinery --
|
||||
|
||||
/// A campaign has one section where a ticket has four, and the section table in `util.rs` is
|
||||
/// what both go through. So the surgery has to land against `## Metadata`, which is the only
|
||||
/// heading that follows a campaign's description, and leave everything outside the body
|
||||
/// alone: a handwritten section, the owner, and the codename in its place.
|
||||
#[test]
|
||||
fn the_description_is_edited_in_place_in_a_file_with_one_section() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["campaign", "set", "v1", "-d", "Replaced."]);
|
||||
run(&temp, &["campaign", "append", "v1", "-d", "Added."]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("## Description\nReplaced.\n\nAdded.\n"), "{content}");
|
||||
// Nothing outside the body moved: the section that follows it, the handwritten one
|
||||
// between them, and the fields under it.
|
||||
assert!(content.contains("## Notes\nA handwritten note."), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(!content.contains("**Status**"), "a status was invented: {content}");
|
||||
// And no section a campaign does not have was inserted to anchor against.
|
||||
assert!(!content.contains("## Acceptance Criteria"), "{content}");
|
||||
assert!(!content.contains("## Implementation Plan"), "{content}");
|
||||
}
|
||||
|
||||
/// The heading is the one in the section table, so `campaign set --description` reaches the
|
||||
/// section `campaign_body` wrote and `campaign show` prints. A second spelling scoped to
|
||||
/// campaigns is what this would catch.
|
||||
#[test]
|
||||
fn the_description_a_campaign_is_filed_with_is_the_one_set_replaces() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"Filed with prose",
|
||||
"--description",
|
||||
"As filed.",
|
||||
],
|
||||
);
|
||||
run(&temp, &["campaign", "set", "Filed with prose", "-d", "As replaced."]);
|
||||
|
||||
let out = run(&temp, &["campaign", "show", "Filed with prose"]);
|
||||
let shown = stdout(&out);
|
||||
assert!(shown.contains("As replaced."), "{shown}");
|
||||
assert!(!shown.contains("As filed."), "{shown}");
|
||||
// One Description heading in the file, not a second one written beside it.
|
||||
let names = campaigns(&worklane);
|
||||
let name = names
|
||||
.iter()
|
||||
.find(|name| name.ends_with("_filed-with-prose.md"))
|
||||
.expect("not filed");
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
assert_eq!(content.matches("## Description").count(), 1, "{content}");
|
||||
}
|
||||
|
||||
/// A campaign file with no Description heading is refused rather than given one back. Every
|
||||
/// campaign the tool files carries the heading, so an insertion path here would be reachable
|
||||
/// only from a hand-edited file, which is the opposite of the Relations case. The message
|
||||
/// names the section and not the object, because both a ticket and a campaign reach it.
|
||||
#[test]
|
||||
fn a_campaign_with_no_description_section_is_refused() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let original = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
original.replace("## Description\nWhat has to ship together.\n\n", ""),
|
||||
)
|
||||
.unwrap();
|
||||
let before = fs::read_to_string(&path).unwrap();
|
||||
|
||||
for args in [
|
||||
["campaign", "set", "v1 release", "-d", "Text."],
|
||||
["campaign", "append", "v1 release", "-d", "Text."],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
assert!(said.contains("no description section"), "{said}");
|
||||
assert!(!said.contains("Ticket"), "a campaign was called a ticket: {said}");
|
||||
assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written");
|
||||
}
|
||||
}
|
||||
|
||||
+1
-1
@@ -314,7 +314,7 @@ fn check_leaves_nothing_behind() {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect();
|
||||
assert_eq!(strays, Vec::<String>::new());
|
||||
|
||||
+1
-1
@@ -77,7 +77,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
+150
-30
@@ -41,6 +41,24 @@ fn create_ticket(worklane_dir: &Path, status: &str, title: &str) -> String {
|
||||
uuid
|
||||
}
|
||||
|
||||
/// The one comment on a ticket, which every author test writes exactly one of.
|
||||
fn only_comment(worklane_dir: &Path, uuid: &str) -> String {
|
||||
let files: Vec<_> = fs::read_dir(worklane_dir.join("history").join(uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
assert_eq!(files.len(), 1, "expected one comment");
|
||||
fs::read_to_string(files[0].path()).unwrap()
|
||||
}
|
||||
|
||||
/// A git config file holding nothing but a `user.name`, for the tests that need the
|
||||
/// fallback to answer something known instead of whatever the machine is configured with.
|
||||
fn git_config_naming(temp: &TempDir, name: &str) -> PathBuf {
|
||||
let path = temp.path().join("gitconfig");
|
||||
fs::write(&path, format!("[user]\n\tname = {}\n", name)).unwrap();
|
||||
path
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_creates_file_with_valid_ticket_uuid() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -55,9 +73,9 @@ fn comment_creates_file_with_valid_ticket_uuid() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
assert!(comments_dir.exists());
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
assert!(history_dir.exists());
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -107,8 +125,8 @@ fn comment_includes_git_user_and_body() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -131,8 +149,8 @@ fn comment_stored_in_timestamped_file() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -142,14 +160,14 @@ fn comment_stored_in_timestamped_file() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_creates_comments_directory() {
|
||||
fn comment_creates_the_history_directory() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let uuid = create_ticket(&worklane, "reviewing", "Dir Test");
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
assert!(!comments_dir.exists());
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
assert!(!history_dir.exists());
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
@@ -158,36 +176,138 @@ fn comment_creates_comments_directory() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(comments_dir.exists());
|
||||
assert!(history_dir.exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_uses_owner_flag_when_provided() {
|
||||
fn comment_uses_actor_flag_when_provided() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let uuid = create_ticket(&worklane, "backlog", "Owner Test");
|
||||
let uuid = create_ticket(&worklane, "backlog", "Actor Test");
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path())
|
||||
.arg("comment")
|
||||
.args([&uuid, "Test comment with owner"])
|
||||
.arg("-o")
|
||||
.arg("TestUser")
|
||||
.args([&uuid, "Test comment with actor"])
|
||||
.args(["--actor", "TestUser"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: TestUser"));
|
||||
}
|
||||
|
||||
/// The flag it was, which named the ticket's assignee and not the writer of the entry.
|
||||
/// Renamed without an alias, so the old spelling is a usage error rather than something
|
||||
/// that half works.
|
||||
#[test]
|
||||
fn the_owner_flag_is_gone() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Gone Test");
|
||||
|
||||
for flag in ["--owner", "-o"] {
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.arg("comment")
|
||||
.args([&uuid, "A body"])
|
||||
.args([flag, "TestUser"])
|
||||
.assert()
|
||||
.failure();
|
||||
}
|
||||
|
||||
assert!(
|
||||
!worklane.join("history").join(&uuid).exists(),
|
||||
"a comment was written despite the usage error"
|
||||
);
|
||||
}
|
||||
|
||||
/// The variable is the case an agent runs in: set once by its configuration and
|
||||
/// inherited by every call, where a flag can be forgotten on the fortieth one.
|
||||
#[test]
|
||||
fn comment_takes_the_author_from_the_actor_variable() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Variable Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
let content = fs::read_to_string(files[0].path()).unwrap();
|
||||
assert!(content.contains("**Author**: TestUser"));
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by an agent"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: claude"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_falls_back_to_git_user_when_owner_omitted() {
|
||||
fn the_actor_flag_overrides_the_variable() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Override Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by the other one"])
|
||||
.args(["--actor", "opencode"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: opencode"));
|
||||
}
|
||||
|
||||
/// An empty variable counts as unset, the convention `NO_COLOR` follows, so a wrapper
|
||||
/// script can clear an inherited one and get the git user back.
|
||||
#[test]
|
||||
fn an_empty_actor_variable_falls_through_to_the_git_user() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Empty Variable Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "")
|
||||
.env("GIT_CONFIG_GLOBAL", git_config_naming(&temp, "Configured User"))
|
||||
.env("GIT_CONFIG_NOSYSTEM", "1")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by a person"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: Configured User"));
|
||||
}
|
||||
|
||||
/// The last resort. Reached with a git that has no `user.name`, which is why the config
|
||||
/// files are redirected: the machine running the suite has one.
|
||||
#[test]
|
||||
fn the_author_is_unknown_when_nothing_names_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let uuid = create_ticket(&worklane, "backlog", "Unknown Test");
|
||||
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env_remove("WORKLANE_ACTOR")
|
||||
.env("GIT_CONFIG_GLOBAL", temp.path().join("no-such-gitconfig"))
|
||||
.env("GIT_CONFIG_NOSYSTEM", "1")
|
||||
.arg("comment")
|
||||
.args([&uuid, "Written by nobody in particular"])
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
assert!(only_comment(&worklane, &uuid).contains("**Author**: unknown"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comment_falls_back_to_git_user_when_actor_omitted() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
@@ -200,8 +320,8 @@ fn comment_falls_back_to_git_user_when_owner_omitted() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -228,8 +348,8 @@ fn comments_added_back_to_back_are_both_kept() {
|
||||
.success();
|
||||
}
|
||||
|
||||
let comments_dir = worklane.join("comments").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&comments_dir)
|
||||
let history_dir = worklane.join("history").join(&uuid);
|
||||
let files: Vec<_> = fs::read_dir(&history_dir)
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.collect();
|
||||
@@ -263,7 +383,7 @@ fn comment_accepts_a_body_that_begins_with_a_hyphen() {
|
||||
.success();
|
||||
}
|
||||
|
||||
let bodies: String = fs::read_dir(worklane.join("comments").join(&uuid))
|
||||
let bodies: String = fs::read_dir(worklane.join("history").join(&uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| fs::read_to_string(e.path()).unwrap())
|
||||
@@ -318,7 +438,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains("<BODY>"), "unclear error: {stderr}");
|
||||
assert!(
|
||||
!worklane.join("comments").join(&uuid).exists(),
|
||||
!worklane.join("history").join(&uuid).exists(),
|
||||
"a comment was written despite the error"
|
||||
);
|
||||
|
||||
@@ -328,7 +448,7 @@ fn a_bare_double_hyphen_body_needs_a_separator() {
|
||||
.assert()
|
||||
.success();
|
||||
|
||||
let stored: String = fs::read_dir(worklane.join("comments").join(&uuid))
|
||||
let stored: String = fs::read_dir(worklane.join("history").join(&uuid))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| fs::read_to_string(e.path()).unwrap())
|
||||
|
||||
+1
-1
@@ -474,7 +474,7 @@ fn stray_files(worklane: &std::path::Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect();
|
||||
|
||||
|
||||
+1
-1
@@ -80,7 +80,7 @@ fn stray_files(worklane: &Path) -> Vec<String> {
|
||||
.filter_map(|e| e.ok())
|
||||
.map(|e| e.file_name().into_string().unwrap())
|
||||
.filter(|name| {
|
||||
!["backlog", "committed", "reviewing", "done", "comments"].contains(&name.as_str())
|
||||
!["backlog", "committed", "reviewing", "done", "history"].contains(&name.as_str())
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
+232
-11
@@ -5,10 +5,11 @@
|
||||
//! 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.
|
||||
//! `tags add` is the other half of the same question. The file reports the vocabulary the
|
||||
//! board *intends* and the tickets carry the one it *has*, and the tests below are mostly
|
||||
//! about the two being allowed to disagree without either one damaging the other. The
|
||||
//! listing reports both and marks which is which, so the tests for the output shape are
|
||||
//! about the marking: which field it lands in, and what a board with no file still prints.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
@@ -380,19 +381,113 @@ fn a_vocabulary_that_cannot_be_read_is_refused_rather_than_replaced() {
|
||||
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.
|
||||
/// The listing is the union of the two vocabularies, and the two disagreeing is the normal
|
||||
/// state rather than a fault: a declaration tags no ticket, and tagging a ticket declares
|
||||
/// nothing.
|
||||
///
|
||||
/// Both halves of the disagreement in one assertion, since neither is legible without the
|
||||
/// other. `chore` is declared and carried by nothing, so it lists at zero with what it
|
||||
/// means; `bug` is carried and declared by nothing, so it lists with a count and no third
|
||||
/// field at all.
|
||||
#[test]
|
||||
fn a_declared_tag_is_not_a_carried_one() {
|
||||
fn the_listing_is_the_union_of_the_declared_and_the_carried() {
|
||||
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"]);
|
||||
assert_eq!(tags(&temp), vec!["bug\t1", "chore\t0\tHousekeeping."]);
|
||||
}
|
||||
|
||||
/// The third field is the annotation's *opening* line. An annotation is prose with
|
||||
/// paragraphs in it, and a second line in this output would be read as a second tag.
|
||||
#[test]
|
||||
fn the_annotation_is_cut_to_its_opening_line() {
|
||||
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!(tags(&temp), vec!["bug\t0\tWhat it is."]);
|
||||
}
|
||||
|
||||
/// A tag declared with nothing said about it still carries a third field, and it is the
|
||||
/// placeholder the file itself holds under that heading.
|
||||
///
|
||||
/// The subtle case, and the reason the field is not simply left empty: an empty third field
|
||||
/// is a trailing tab, so the only difference between a declared tag and an undeclared one
|
||||
/// would be invisible in a terminal and in a completion alike.
|
||||
#[test]
|
||||
fn a_tag_declared_without_an_annotation_is_still_marked_as_declared() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried");
|
||||
|
||||
run(&temp, &["tags", "add", "declared"]);
|
||||
|
||||
assert_eq!(tags(&temp), vec!["carried\t1", "declared\t0\t_No annotation provided._"]);
|
||||
}
|
||||
|
||||
/// `cut -f1` over the listing yields exactly the tag values, undeclared ones included.
|
||||
///
|
||||
/// The constraint the whole output shape is built around: whatever marks a carried but
|
||||
/// undeclared tag must stay out of the first field, or a completion offers a tag that does
|
||||
/// not exist and `ls --tag` comes back empty for it.
|
||||
#[test]
|
||||
fn the_first_field_is_the_bare_tag_whether_it_is_declared_or_not() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "carried,both");
|
||||
run(&temp, &["tags", "add", "both", "-a", "Carried and declared."]);
|
||||
run(&temp, &["tags", "add", "declared", "-a", "Declared only."]);
|
||||
|
||||
let first: Vec<String> = tags(&temp)
|
||||
.iter()
|
||||
.map(|line| line.split('\t').next().unwrap().to_string())
|
||||
.collect();
|
||||
assert_eq!(first, vec!["both", "carried", "declared"]);
|
||||
|
||||
// And each of them is a value `--tag` can match, which is what the first field is for.
|
||||
for tag in ["both", "carried"] {
|
||||
let out = run(&temp, &["ls", "--tag", tag, "--ids"]);
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&out.stdout).lines().count(),
|
||||
1,
|
||||
"--tag {tag} matched nothing"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// A board with no vocabulary lists what it listed before the file existed, byte for byte.
|
||||
///
|
||||
/// Every tag on such a board is carried and undeclared, so the absence of the third field
|
||||
/// is what keeps the old output shape: a marker in it would have changed every line of
|
||||
/// every board that predates the file, and the shipped fish completion of an older version
|
||||
/// is still reading this.
|
||||
#[test]
|
||||
fn a_board_with_no_vocabulary_lists_what_it_listed_before_the_file_existed() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
create_ticket(&worklane, "done", "22222222", "bug");
|
||||
assert!(!temp.path().join(".worklane").join("tags.md").exists());
|
||||
|
||||
let out = run(&temp, &["tags"]);
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), "bug\t2\ncli\t1\n");
|
||||
}
|
||||
|
||||
/// The bare form is the listing, byte for byte, because the shipped fish completion calls it
|
||||
@@ -409,5 +504,131 @@ fn the_bare_form_and_ls_are_the_same_listing() {
|
||||
|
||||
assert!(bare.status.success());
|
||||
assert_eq!(bare.stdout, group.stdout);
|
||||
assert_eq!(String::from_utf8_lossy(&bare.stdout), "bug\t1\ncli\t1\n");
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&bare.stdout),
|
||||
"bug\t1\nchore\t0\t_No annotation provided._\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."));
|
||||
}
|
||||
|
||||
@@ -0,0 +1,351 @@
|
||||
//! The history log: what the CLI records about a ticket besides what somebody said.
|
||||
//!
|
||||
//! One file rather than a few tests in each command's suite: the rules are about the log
|
||||
//! and not about `mv` or `chown`, and the interesting cases are the ones where two
|
||||
//! commands have to agree — every mechanical entry has the same shape, and every refusal
|
||||
//! writes nothing.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::Output;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
const UUID: &str = "475534a3-8a0d-45cb-9a97-39c251dd8e39";
|
||||
|
||||
fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
let worklane = temp.child(".worklane");
|
||||
worklane.create_dir_all().unwrap();
|
||||
|
||||
for dir in ["backlog", "committed", "reviewing", "done"] {
|
||||
worklane.child(dir).create_dir_all().unwrap();
|
||||
}
|
||||
|
||||
worklane.path().to_path_buf()
|
||||
}
|
||||
|
||||
/// A ticket with every field an entry can record a change to.
|
||||
fn create_ticket(worklane: &Path, status: &str) -> String {
|
||||
let filename = format!("{}_a-ticket.md", UUID);
|
||||
fs::write(
|
||||
worklane.join(status).join(&filename),
|
||||
format!(
|
||||
"# A ticket\n\
|
||||
\n\
|
||||
## Description\n\
|
||||
Something to do.\n\
|
||||
\n\
|
||||
## Acceptance Criteria\n\
|
||||
- [ ] Crit one\n\
|
||||
- [ ] Crit two\n\
|
||||
\n\
|
||||
## Implementation Plan\n\
|
||||
1. Step one\n\
|
||||
\n\
|
||||
## Metadata\n\
|
||||
\n\
|
||||
- **ID**: {}\n\
|
||||
- **Priority**: 3\n\
|
||||
- **Tags**: alpha\n\
|
||||
- **Due**: 2026-09-01\n\
|
||||
- **Owner**: alice\n\
|
||||
- **Status**: {}\n",
|
||||
UUID, status
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
filename
|
||||
}
|
||||
|
||||
/// Run with the actor named, so every author assertion is about the log and not about
|
||||
/// the git user of whoever runs the suite.
|
||||
fn run(temp: &TempDir, args: &[&str]) -> Output {
|
||||
Command::cargo_bin(BIN_NAME)
|
||||
.unwrap()
|
||||
.current_dir(temp.path())
|
||||
.env("WORKLANE_ACTOR", "claude")
|
||||
.args(args)
|
||||
.assert()
|
||||
.get_output()
|
||||
.clone()
|
||||
}
|
||||
|
||||
/// Every entry on the ticket, name and content, in the order the log sorts them.
|
||||
fn entries(worklane: &Path) -> Vec<(String, String)> {
|
||||
let dir = worklane.join("history").join(UUID);
|
||||
if !dir.exists() {
|
||||
return vec![];
|
||||
}
|
||||
|
||||
let mut found: Vec<(String, String)> = fs::read_dir(&dir)
|
||||
.unwrap()
|
||||
.filter_map(|entry| entry.ok())
|
||||
.map(|entry| {
|
||||
(
|
||||
entry.file_name().into_string().unwrap(),
|
||||
fs::read_to_string(entry.path()).unwrap(),
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
found.sort_by(|a, b| a.0.cmp(&b.0));
|
||||
found
|
||||
}
|
||||
|
||||
/// The one entry a call wrote, with its kind checked off the filename.
|
||||
fn only_entry(worklane: &Path, kind: &str) -> String {
|
||||
let found = entries(worklane);
|
||||
assert_eq!(found.len(), 1, "expected one entry, got {found:?}");
|
||||
assert!(found[0].0.ends_with(&format!("_{kind}.md")), "was {}", found[0].0);
|
||||
found[0].1.clone()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mv_writes_a_status_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
|
||||
let entry = only_entry(&worklane, "status");
|
||||
assert!(entry.starts_with("**Status**\nbacklog → committed\n"), "{entry:?}");
|
||||
assert!(entry.contains("**Author**: claude"), "{entry:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chown_writes_an_owner_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["chown", "bob", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "owner");
|
||||
assert!(entry.starts_with("**Owner**\nalice → bob\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// Clearing is the same field going somewhere, so it is logged, and the value it goes to
|
||||
/// is the sentinel the ticket now holds rather than a word this log invented.
|
||||
#[test]
|
||||
fn clearing_the_owner_writes_an_owner_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["chown", "--clear", UUID]);
|
||||
|
||||
let entry = only_entry(&worklane, "owner");
|
||||
assert!(entry.starts_with("**Owner**\nalice → _Not set_\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn set_tags_writes_a_tags_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["set", UUID, "--tags", "beta", "--tags", "gamma"]);
|
||||
|
||||
let entry = only_entry(&worklane, "tags");
|
||||
assert!(entry.starts_with("**Tags**\nalpha → beta, gamma\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clearing_the_tags_writes_a_tags_entry() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["set", UUID, "--clear", "tags"]);
|
||||
|
||||
let entry = only_entry(&worklane, "tags");
|
||||
assert!(entry.starts_with("**Tags**\nalpha → _None_\n"), "{entry:?}");
|
||||
}
|
||||
|
||||
/// The fields that change often enough that a log of them is noise. `set` writing one of
|
||||
/// them is not an entry, and neither is a criterion being ticked.
|
||||
#[test]
|
||||
fn the_edits_that_are_not_logged_write_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
for args in [
|
||||
vec!["set", UUID, "--title", "A better title"],
|
||||
vec!["set", UUID, "--due", "2026-10-01"],
|
||||
vec!["set", UUID, "--priority", "1"],
|
||||
vec!["set", UUID, "--description", "Rewritten."],
|
||||
vec!["set", UUID, "--plan", "One step"],
|
||||
vec!["check", UUID, "1"],
|
||||
vec!["uncheck", UUID, "1"],
|
||||
vec!["append", UUID, "--description", "One more paragraph."],
|
||||
vec!["comment", UUID, "-", "--"],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{args:?}: {:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
}
|
||||
|
||||
// The comment is the exception: it is an entry, and the only one this run wrote.
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 1, "{found:?}");
|
||||
assert!(found[0].0.ends_with("_comment.md"), "was {}", found[0].0);
|
||||
}
|
||||
|
||||
/// An edit reported as no change writes no entry: the field is already what the call
|
||||
/// asked for, and a log of that would be a log of nothing happening.
|
||||
#[test]
|
||||
fn a_no_op_edit_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
for args in [
|
||||
vec!["mv", UUID, "--status", "backlog"],
|
||||
vec!["chown", "alice", UUID],
|
||||
vec!["set", UUID, "--tags", "alpha"],
|
||||
] {
|
||||
let out = run(&temp, &args);
|
||||
assert!(
|
||||
out.status.success(),
|
||||
"{args:?}: {:?}",
|
||||
String::from_utf8_lossy(&out.stderr)
|
||||
);
|
||||
assert_eq!(entries(&worklane), vec![], "{args:?} logged a change it did not make");
|
||||
}
|
||||
}
|
||||
|
||||
/// A refused move is not a move. The entry is written after the edit for exactly this.
|
||||
#[test]
|
||||
fn a_refused_move_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "reviewing");
|
||||
|
||||
let backward = run(&temp, &["mv", UUID, "--status", "backlog"]);
|
||||
assert_eq!(backward.status.code(), Some(1));
|
||||
|
||||
let skipped = run(&temp, &["mv", UUID, "--status", "backlog", "-f"]);
|
||||
assert!(skipped.status.success(), "{:?}", String::from_utf8_lossy(&skipped.stderr));
|
||||
|
||||
// The forced one moved, so it is logged; the refused one is not.
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 1, "{found:?}");
|
||||
assert!(found[0].1.contains("reviewing → backlog"), "{:?}", found[0].1);
|
||||
}
|
||||
|
||||
/// A failed edit logs nothing, whatever the failure. This ticket has no Owner field, so
|
||||
/// `chown` refuses it after resolving it and before writing anything.
|
||||
#[test]
|
||||
fn a_failed_edit_writes_nothing() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
fs::write(
|
||||
worklane.join("backlog").join(format!("{}_bare.md", UUID)),
|
||||
format!("# Bare\n\n## Metadata\n\n- **ID**: {}\n- **Status**: backlog\n", UUID),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["chown", "bob", UUID]);
|
||||
assert_eq!(out.status.code(), Some(1));
|
||||
assert_eq!(entries(&worklane), vec![], "a refused chown was logged");
|
||||
}
|
||||
|
||||
/// One sequence, oldest first, with a comment rendered as it always was and a field
|
||||
/// change as one line.
|
||||
#[test]
|
||||
fn show_prints_the_comments_and_the_changes_in_one_sequence() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["comment", UUID, "Picked this up."]);
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
run(&temp, &["chown", "bob", UUID]);
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
let stdout = String::from_utf8(out.stdout).unwrap();
|
||||
|
||||
assert!(stdout.contains("HISTORY"), "{stdout}");
|
||||
let said = stdout.find("Picked this up.").expect("the comment is missing");
|
||||
let moved = stdout.find("backlog → committed").expect("the move is missing");
|
||||
let owned = stdout.find("alice → bob").expect("the chown is missing");
|
||||
assert!(said < moved && moved < owned, "out of order:\n{stdout}");
|
||||
|
||||
for line in ["status backlog → committed", "owner alice → bob"] {
|
||||
assert!(stdout.contains(line), "{line:?} not in:\n{stdout}");
|
||||
}
|
||||
assert!(stdout.contains("From claude ("), "{stdout}");
|
||||
}
|
||||
|
||||
/// A ticket nothing has happened to says so, where it used to say there were no comments.
|
||||
#[test]
|
||||
fn show_says_so_when_there_is_no_history() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
assert!(
|
||||
String::from_utf8(out.stdout)
|
||||
.unwrap()
|
||||
.contains("No history yet.")
|
||||
);
|
||||
}
|
||||
|
||||
/// A board written by an older version: the directory is adopted on the first access,
|
||||
/// the entries in it are read as the comments they are, and nothing is rewritten.
|
||||
#[test]
|
||||
fn an_old_comments_directory_is_adopted() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
let legacy = worklane.join("comments").join(UUID);
|
||||
fs::create_dir_all(&legacy).unwrap();
|
||||
let name = "20260820_143012_123456.md";
|
||||
let content =
|
||||
"**Comment**\nSaid long ago.\n\n**Author**: Ansho Rei\n**Time**: 2026-08-20 14:30:12\n";
|
||||
fs::write(legacy.join(name), content).unwrap();
|
||||
|
||||
let out = run(&temp, &["show", UUID]);
|
||||
let stdout = String::from_utf8(out.stdout).unwrap();
|
||||
assert!(stdout.contains("Said long ago."), "{stdout}");
|
||||
assert!(stdout.contains("From Ansho Rei ("), "{stdout}");
|
||||
|
||||
assert!(!worklane.join("comments").exists(), "the old directory survived");
|
||||
let moved = worklane.join("history").join(UUID).join(name);
|
||||
assert_eq!(fs::read_to_string(&moved).unwrap(), content, "the entry was rewritten");
|
||||
|
||||
// And a new entry lands beside it, in the order it was written.
|
||||
run(&temp, &["mv", UUID, "--status", "committed"]);
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 2, "{found:?}");
|
||||
assert_eq!(found[0].0, name);
|
||||
assert!(found[1].0.ends_with("_status.md"), "was {}", found[1].0);
|
||||
}
|
||||
|
||||
/// The flag is spelled the same on every command that writes an entry, and it overrides
|
||||
/// the variable on each of them.
|
||||
#[test]
|
||||
fn the_actor_flag_names_the_writer_on_every_command_that_writes_one() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog");
|
||||
|
||||
run(&temp, &["comment", UUID, "By hand.", "--actor", "opencode"]);
|
||||
run(&temp, &["mv", UUID, "--status", "committed", "--actor", "opencode"]);
|
||||
run(&temp, &["chown", "bob", UUID, "--actor", "opencode"]);
|
||||
run(&temp, &["set", UUID, "--tags", "beta", "--actor", "opencode"]);
|
||||
|
||||
let found = entries(&worklane);
|
||||
assert_eq!(found.len(), 4, "{found:?}");
|
||||
for (name, content) in found {
|
||||
assert!(content.contains("**Author**: opencode"), "{name}: {content:?}");
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user