Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
50e67483d8 | ||
|
|
11145b228e | ||
|
|
2ddd0addf6 | ||
|
|
cbc20848f6 | ||
|
|
eae411ab50 | ||
|
|
95426e87be | ||
|
|
72dbdec2ec | ||
|
|
528566d103 | ||
|
|
c65e1b4ed7 |
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
---
|
||||
|
||||
# Feature Planner Agent
|
||||
|
||||
@@ -17,7 +17,7 @@ permissions:
|
||||
bash:
|
||||
"sudo *": "deny"
|
||||
skill:
|
||||
"worklane_kanban": "allow"
|
||||
"worklane": "allow"
|
||||
"testing-skill": "allow"
|
||||
---
|
||||
|
||||
|
||||
@@ -1,223 +0,0 @@
|
||||
---
|
||||
id: worklane_kanban
|
||||
name: worklane_kanban
|
||||
version: 1.0.0
|
||||
description: >
|
||||
Creates Kanban-style tickets in Worklane using the `worklane add` CLI command.
|
||||
Supports listing tickets with `worklane ls`. Both commands support title, description,
|
||||
acceptance criteria, implementation plan, tags, due date, owner assignment, and status filtering.
|
||||
rendering:
|
||||
strategy: cli_args
|
||||
join_arrays_with: ","
|
||||
omit_empty: true
|
||||
---
|
||||
|
||||
# Worklane Kanban Skill
|
||||
|
||||
Use this skill when creating, listing, or managing Kanban-style tickets via the `worklane` CLI.
|
||||
|
||||
When asked to "create a ticket", use the `worklane add` command.
|
||||
When using backticks in the command arguments, escape them so the terminal doesn't execute them.
|
||||
|
||||
When asked to "implement", "work on" or "read" a ticket, use the `worklane show` command.
|
||||
|
||||
## Commands
|
||||
|
||||
### `worklane add`
|
||||
|
||||
Add a new ticket to the backlog.
|
||||
|
||||
**Required:**
|
||||
- `--title` (or `-t`): Ticket title
|
||||
|
||||
**Optional:**
|
||||
- `--description` (or `-d`): Ticket description
|
||||
- `--acceptance` (or `-a`): Acceptance criteria (repeat flag for each criterium)
|
||||
- `--plan` (or `-p`): Implementation plan steps (repeat flag for each step)
|
||||
- `--tags` (or `-g`): Tags (comma-separated)
|
||||
- `--due`: Due date in YYYY-MM-DD format. No short form
|
||||
- `--owner` (or `-o`): Owner name
|
||||
- `--priority`: Priority level, 1 (most urgent) to 5 (least). Unset if omitted. No short form
|
||||
|
||||
Tags are `-g`, not `-t`: `-t` is the title, and passing it twice is an error. Each
|
||||
plan step needs its own `-p`, since a bare value after one is not a second step.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement login" -d "Add user login page" -g login,auth -p "Design UI" -p "Build backend" -p "Write tests" --due 2026-06-01 --owner "ilya"
|
||||
```
|
||||
|
||||
When there's multiple acceptance criteria, add each using a separate `--acceptance` or `-a` flag.
|
||||
When there's mulitple steps to the implementation plan, add each using a separate `--plan` or `-p` flag.
|
||||
|
||||
```bash
|
||||
worklane add -t "Implement logic" -a "Acceptance criterium 1" -a "Acceptance criterium 2" -p "Step 1" -p "Step 2"
|
||||
```
|
||||
|
||||
### `worklane ls`
|
||||
|
||||
List tickets, optionally filtered by status.
|
||||
|
||||
**Valid statuses:** `backlog`, `committed`, `reviewing`, `done`
|
||||
|
||||
```
|
||||
worklane ls # List all tickets
|
||||
worklane ls backlog # List tickets in backlog
|
||||
worklane ls done # List completed tickets
|
||||
worklane ls --priority 1 # Only the most urgent, any status
|
||||
worklane ls backlog --priority 2 # Composes with the status filter
|
||||
```
|
||||
|
||||
Tickets are listed priority first, then by title. Tickets with no priority sort last.
|
||||
|
||||
### `worklane show`
|
||||
|
||||
Show the full details of a single ticket by UUID or title.
|
||||
|
||||
```
|
||||
worklane show "ticket title or uuid"
|
||||
```
|
||||
|
||||
### `worklane mv`
|
||||
|
||||
Move a ticket between statuses.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<id>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Required options:**
|
||||
- `--status <target>`: Target status (`backlog`, `committed`, `reviewing`, `done`)
|
||||
|
||||
**Options:**
|
||||
- `-f`: Force move (allows skipping stages and backward moves)
|
||||
|
||||
**Default behavior:** Only allows forward moves, one stage at a time (`backlog` -> `committed` -> `reviewing` -> `done`).
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane mv ticket-id --status committed # Move forward one stage
|
||||
worklane mv ticket-title --status reviewing -f # Force skip stages
|
||||
worklane mv a1b2c3d4 --status committed # Move by UUID prefix
|
||||
worklane mv "My Ticket" --status done -f # Move by title with force
|
||||
```
|
||||
|
||||
### `worklane set`
|
||||
|
||||
Replace fields on an existing ticket. Only the fields given are touched; ticked
|
||||
criteria and handwritten sections are left alone. At least one field is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--title`, `--description` (or `-d`), `--acceptance` (or `-a`), `--plan`
|
||||
(or `-p`), `--tags` (or `-g`), `--due`, `--priority`
|
||||
|
||||
Owner is not settable here, and neither is status: `chown` owns owner and `mv` owns
|
||||
status. Changing the title renames the file, keeping the UUID.
|
||||
|
||||
```bash
|
||||
worklane set a1b2c3d4 --priority 1
|
||||
worklane set a1b2c3d4 --title "A clearer title" --due 2026-12-31
|
||||
worklane set a1b2c3d4 -a "First criterium" -a "Second criterium"
|
||||
```
|
||||
|
||||
### `worklane append`
|
||||
|
||||
Add to a section without replacing what is there. The description gains a new
|
||||
paragraph; criteria and steps go on the end of their lists, steps numbered on from
|
||||
the last. At least one section is required.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
**Options:** `--description` (or `-d`), `--acceptance` (or `-a`), `--plan` (or `-p`)
|
||||
|
||||
```bash
|
||||
worklane append a1b2c3d4 -d "A paragraph amending the description."
|
||||
worklane append a1b2c3d4 -a "One more criterium"
|
||||
worklane append a1b2c3d4 -p "A later step"
|
||||
```
|
||||
|
||||
### `worklane chown`
|
||||
|
||||
Set the owner of a ticket. The only command that writes the Owner field: `set` does
|
||||
not offer it.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<user>`: The new owner. Free text, checked against nothing
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
|
||||
The user comes first and the ticket second, after Unix `chown`. That is the one
|
||||
command here that does not start with the ticket, so mind the order: swap the two and
|
||||
the call fails, because the username has to resolve as a ticket. An owner set to the
|
||||
value it already holds is reported unchanged and nothing is written.
|
||||
|
||||
```bash
|
||||
worklane chown alice a1b2c3d4
|
||||
worklane chown "Ansho Rei" "A clearer title"
|
||||
```
|
||||
|
||||
### `worklane check` and `worklane uncheck`
|
||||
|
||||
Tick or untick a single acceptance criterion. Every other criterion keeps its state,
|
||||
and handwritten lines in the section are left alone.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `[criterion]`: The number as shown by `worklane show`, or a substring of its text
|
||||
|
||||
Omit the criterion and the numbered criteria are listed and the number asked for. With
|
||||
no terminal, as when driving the CLI from a tool, the same list comes back as an error
|
||||
instead, so re-run with the number. A substring matching more than one criterion is an
|
||||
error listing the matches with their real numbers.
|
||||
|
||||
```bash
|
||||
worklane check a1b2c3d4 2
|
||||
worklane check a1b2c3d4 "renames the file"
|
||||
worklane uncheck a1b2c3d4 2
|
||||
```
|
||||
|
||||
### `worklane comment`
|
||||
|
||||
Add a comment to a ticket.
|
||||
|
||||
**Positional arguments:**
|
||||
- `<ticket>`: Ticket UUID prefix (4+ characters) or title
|
||||
- `<body>`: Comment text
|
||||
|
||||
Comments are stored as timestamped markdown files in `.worklane/comments/<ticket-uuid>/` and include the git author and timestamp.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
worklane comment ticket-id "Reviewed, looks good"
|
||||
worklane comment "My Ticket" "Needs changes to the UI"
|
||||
worklane comment a1b2c3d4 "LGTM, approved"
|
||||
```
|
||||
|
||||
## Working a ticket
|
||||
|
||||
Move the ticket as you work it, not afterwards. The board should say what is happening
|
||||
now, not only what already landed.
|
||||
|
||||
1. `worklane show <id>` to read it
|
||||
2. **`worklane mv <id> --status committed` before writing any code.** This is what marks
|
||||
the ticket as being worked on, so it belongs at the start
|
||||
3. Do the work. `worklane check <id> <n>` as each criterion is met
|
||||
4. `worklane comment <id> <body>` with anything worth recording: a decision, a rejected
|
||||
acceptance criterion, something the ticket got wrong
|
||||
5. **`worklane mv <id> --status reviewing` once it is done and the tests pass**
|
||||
|
||||
Only one stage forward is allowed at a time, so a ticket left in `backlog` until the end
|
||||
cannot go straight to `reviewing`. It has to be walked through `committed` anyway, which
|
||||
makes moving it up front the same two commands in a more useful order.
|
||||
|
||||
## Commands
|
||||
|
||||
- `worklane add` creates tickets with all relevant details
|
||||
- `worklane ls [status]` views tickets by status
|
||||
- `worklane show <id>` views full ticket details
|
||||
- `worklane mv <id> --status <target>` moves tickets through the workflow
|
||||
- `worklane set <ticket>` corrects a field, `worklane append <ticket>` adds to a section
|
||||
- `worklane check <ticket> <n>` ticks a criterion as it is met
|
||||
- `worklane comment <ticket> <body>` adds notes to tickets
|
||||
@@ -13,6 +13,7 @@
|
||||
- `assets/SKILL.md` - the agent skill for the CLI itself, embedded with `include_str!`
|
||||
- `assets/REVIEW.md` - the agent skill for reviewing a finished ticket, shipped the same way. Assets are named after the role they teach; `SKILL.md` keeps its name because the role it teaches is the CLI
|
||||
- `assets/PLAN.md` - the agent skill for grooming the whole board: priorities, due dates, tags and campaigns
|
||||
- `assets/TOOL.ts` - the opencode tool definitions wrapping the CLI, embedded the same way and installed by `install-tool`. The only asset that is not a document and the only one that reaches a single agent
|
||||
- `tests/` - Integration tests using `assert_cmd` and `assert_fs`, one file per command
|
||||
- Unit tests live beside the code in `#[cfg(test)] mod tests`, in `util.rs`, `handlers.rs` and `tui.rs`
|
||||
- Ticket files stored as `.md` in `.worklane/<status>/` directories
|
||||
@@ -22,9 +23,11 @@
|
||||
- Filenames: `<uuid_v4>_<slug>.md`
|
||||
- The slug is the title through `slug()`: lowercased, alphanumerics plus `-` and `_` kept, spaces turned into dashes. `Ticket 06` lands as `<uuid>_ticket-06.md`. Derive fixture filenames through `slug()`, never by hand
|
||||
- Metadata fields parsed by `parse_ticket_field()`: `ID`, `Priority`, `Tags`, `Due`, `Owner`, `Created At`, `Committed On`, `Submitted On`, `Completed On`, `Campaign`, `Status`. The last four are the ones no ticket is born with: `add` writes none of them, so they are inserted on demand, against `METADATA_ORDER`, which is also what keeps `Status` last
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they are mutually exclusive: entering a status writes its field, leaving removes it, re-entering restamps. So a ticket carries at most one, the one for the status it is sitting in, and a backward move under `-f` leaves no stale `Completed On` behind. They are current state, like `Status` itself; the trail of how the ticket got there is d4ce964's job and must not be grown here. `backlog` has no stamp, `Created At` already answers for it
|
||||
- The three stamps are `mv`'s, written by `set_status_stamp` from `Status::stamp_field`, and they **accumulate**: entering a status writes its field, re-entering restamps, and arriving anywhere removes the fields of every status *after* the target. One arrival rule keyed off `Status::ALL`, not a case per move, which is why a backward move truncates the journey at the target (`done` back to `reviewing` drops `Completed On`, anything back to `backlog` drops all three) and a forward skip under `-f` stamps only where it lands rather than fabricating the stages it jumped. A ticket that walks the whole flow ends with `Created At`, `Committed On`, `Submitted On` and `Completed On` side by side, so presence means *got this far and has not been sent back past it*, not *is here now* — `Status` is what says where it is. Still not d4ce964's history log: these answer how far and when, once per stage, and every change along the way is the log's. `backlog` has no stamp, `Created At` already answers for it
|
||||
- **Each status column is ordered by its own entry stamp, through `by_status_order`.** Priority is the clock in the backlog and that column keeps priority then title; past it the question changes, so committed sorts by `Committed On` ascending, reviewing by `Submitted On` ascending, and done by `Completed On` descending. Said once: the head of every column is what the reader acts on next. An unstamped ticket sinks below every stamped one in its column, because a missing time is unknown rather than ancient and unknown must not claim the head of a queue; equal stamps and both-unstamped fall through to `by_priority_then_title`. One function keyed on the `Status`, taken by both `cmd_ls` branches, `list_ids`, `columns_of` and `campaign::members`, which is why those loops walk `Status::ALL` rather than `status_dirs()`. The stamps are read in `collect_ticket_items`' existing pass, the rule `criteria` and `tags` already hold, and compared as strings: `%Y-%m-%d %H:%M:%S` is lexicographic in chronological order, the property `Due` already relies on, so nothing parses a date at sort time
|
||||
- Format: `**Field Name**: value`
|
||||
- Ticket structure: `# Title` → `## Description` → `## Acceptance Criteria` → `## Implementation Plan` → `## Metadata`
|
||||
- A **campaign** file carries `ID`, `Codename`, `Owner` and `Created At`, in that order, and no `Status`. `Codename` sits directly under the ID because that is what it is, a second way to say which campaign this is; it is written by `campaign add --codename` alone and is `_Not set_` when the flag was not given. It is not in `METADATA_ORDER`, which is the anchor list for the *upsert* on a ticket, and nothing upserts a campaign
|
||||
- Comments stored in `.worklane/comments/<ticket_uuid>/<timestamp>.md` with `**Comment**`, `**Author**`, `**Time**` fields
|
||||
|
||||
## Status Workflow
|
||||
@@ -41,6 +44,7 @@ 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)
|
||||
- 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:
|
||||
|
||||
@@ -74,6 +78,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **The shape is checked before chrono is asked.** `%Y-%m-%d` accepts an unpadded `2026-8-9`, which would be stored exactly as typed and sort before `2026-10-01` in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting
|
||||
- **Strict on the way in, tolerant on the way out.** `util::due_date` still cuts `2026-12-31T09:30:00Z` down to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake
|
||||
- An empty `--due` keeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it
|
||||
- **`campaign add --codename` is validated at parse time by `codename`**, which is `non_empty` plus one word. The board draws it as a label with a mark and no quoting, so `~beaver release` on that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reason `ls --tag` refuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold
|
||||
- **There are two empty-value parsers, and which one an argument takes is the point.** `non_empty` says only that the value cannot be empty, for the arguments with no empty form: the `ls` filters, `relate`'s targets, and `set --title`, which addresses the ticket and names its file. `clearable` names `--clear`, for the arguments whose field does have one: `set --tags`, `--due` through `iso_date`, and the `chown` user. One message for both would either lie about `ls --tag` or leave the useful half unsaid. `add --due` takes the second one because `iso_date` is shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser
|
||||
- **A status is a `util::Status`, not a string.** `mv --status` and the `ls` positional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain `--due` and `--priority` take, and it is what lets the shells complete the four for free. `Status::ALL` is the flow order, which `status_dirs()` and `cmd_mv` both read rather than spelling the names again, and `DONE` is defined from it
|
||||
- The ticket positionals (`show <id>`, `mv <ticket>`, `comment <ticket>`) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with `--`, as in `mv --status committed -- -leading-title`
|
||||
@@ -87,16 +92,20 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **Two halves, and the split is the point.** `clap_complete` generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching `completions.rs`. Only fish gets the second half, appended by `fish_dynamic()`, and it holds exactly what clap cannot know: the tickets on the board
|
||||
- **The dynamic values come from worklane itself**, as `worklane ls --ids` in a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without `--ids` completes nothing, which is a reinstall rather than a bug
|
||||
- **What clap does and does not emit.** It emits the possible values of an *option*, which is why `mv --status <TAB>` needs nothing here, and nothing for a *positional*, which is why the `ls` status and the `completions` shell are listed in the fish half. Both lists are read off the enums with `possible_values`, never written out, so a fifth status appears in the script on its own
|
||||
- **Position is counted, not inferred.** `__worklane_first_arg_of` and `__worklane_second_arg_of` check `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition
|
||||
- **`TICKET_COMMANDS`, `TICKET_SECOND_COMMANDS` and `TICKET_FLAGS` are kept honest by tests**, which walk the clap definition and fail on a ticket-taking subcommand that is in neither list, or in the list for the wrong position. A nested subcommand is not walked: `campaign` is the only one, none of its three takes a ticket, and the token counting could not tell them apart if one did
|
||||
- **`ls --ids` is the machine-readable listing**, and the only output in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused
|
||||
- **Position is counted, not inferred.** The four `__worklane_*` predicates all read `$tokens[2]` and the token count rather than using `__fish_seen_subcommand_from`, because `campaign ls` and `campaign show` are also an `ls` and a `show` that fish has seen, and because matching against the ticket list would run worklane again inside the condition. `first_arg_of` and `second_arg_of` count a top-level command's arguments, `nested_arg_of` matches a parent and a child so `campaign show <TAB>` can be told from `chown alice <TAB>`, which sit at the same token count, and `command_is` asks only which command this is, at any position in it
|
||||
- **Every rule carrying `-l` needs a `__worklane_command_is`, and `every_rule_naming_an_option_is_scoped_to_a_command` is what enforces it.** A bare `complete -c worklane -l tag` does not just complete that option's values, it tells fish the whole tool accepts `--tag`: `worklane init --<TAB>` offered six options that only `relate` and `ls` have. Fixed in 55ee6e3. `__fish_seen_subcommand_from ls` is not the scope to use, for the nesting reason above
|
||||
- **The five completion lists are kept honest by tests** that walk the clap definition and fail on an argument left out of them. `TICKET_COMMANDS` and `TICKET_SECOND_COMMANDS` by position, `TICKET_FLAGS`, `CAMPAIGN_COMMANDS`, `CAMPAIGN_NESTED_COMMANDS`, `CAMPAIGN_FLAGS` and `TAG_FLAGS` likewise. The walk is one function, `every_argument`, since the tests differ only in the id they look for. Each also asserts *how many* it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
|
||||
- **A campaign is named in three shapes and a tag in one**, which is why the lists are not one list: a campaign is `assign`'s first positional, the first argument of `campaign show` and `campaign set`, and `ls --campaign`'s value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command
|
||||
- **`ls --ids` is the machine-readable listing**, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads `cut -f1`. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown `--campaign` is still refused
|
||||
- **`campaign ls --ids` is the same flag and the same two fields for the other object**, and it deliberately skips the member counting the decorated listing does: `members()` reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates
|
||||
- **`worklane tags` is the third, and it is a command rather than a mode on `ls`.** Two reasons: `ls --tag <tag>` answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a `--tags` beside a `--tag` is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so `bug` and `Bug` list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. `assets/PLAN.md` used to tell the agent to count tags with a `show` per ticket, and now points here
|
||||
|
||||
### Filtering the Listing
|
||||
- **The filters are one call, `filtered`,** because `ls` collects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is an `Option` and none asked for keeps everything, which is what makes them compose in any combination without a rule per pair
|
||||
- **`--tag` matches whole values, not the field.** `parse_tags` has already split the comma-separated field, so the filter compares against those trimmed values: `--tag bug` is not answered by a ticket tagged `bugfix`, and `--tag "cli, filter"` matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none
|
||||
- **Case sensitive**, the opinion the field already takes: `tag_color` draws `Bug` and `bug` in two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for
|
||||
- **One tag per invocation.** Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
|
||||
- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, since that is the failure this trades for
|
||||
- **A tag nothing carries lists nothing rather than being refused**, which is the opposite of `--campaign`. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have. `assets/PLAN.md` tells the agent to check the spelling when a listing comes back empty, and `worklane tags` is what it checks against, since that is the failure this trades for
|
||||
- An emptied status keeps the message `ls` already gives, `No tickets in '<status>' status.`, rather than one per filter naming what excluded them. That is pre-existing behaviour for `--priority` and `--campaign`, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket
|
||||
- **`cmd_ls` takes an `LsArgs`**, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacent `Option<String>` values a caller could swap silently. `--ids` was the argument that tipped it, the way `add` became `AddArgs`. A new filter is a field there, not a parameter
|
||||
|
||||
@@ -163,12 +172,19 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **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
|
||||
- **`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 three 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
|
||||
- **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
|
||||
- **An exact `Codename` is the top tier, and it lives in the shared resolver rather than in a campaign-only path.** Only campaigns carry the field, so `parse_codename` returns `None` for every ticket and the tier is always empty for one: ticket resolution is unchanged, which `a_ticket_search_is_unaffected_by_the_codename_tier` pins. It goes above the uuid prefix because it is an exact match on a field written for the purpose, where a substring can be a coincidence, and because a codename like `v1` is below `MIN_ID_SEARCH` and would never be tried as an id at all. A codename that a title also contains, `v2` against `v2 release`, has to win outright rather than be reported ambiguous against it
|
||||
- **`resolve_ticket` explains a search that names a campaign**, rather than each command doing it. One place, so `mv`, `show`, `chown` and everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentioned
|
||||
- **`Resolved` carries what `content_trim` cannot render from the file.** The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call site
|
||||
- `campaign show` lists **done** members, unlike `ls`, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option. `ls --campaign` is the other way round: it is the ordinary board filtered, and keeps every rule `ls` already has
|
||||
- `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 gets neither a campaign tab nor a card marker**, for now. The detail view resolves the field because it renders the body, and that is all. A marker on a card would want a campaigns read per reload, which is more than the blocked mark cost: that one reads the ticket's own Relations section on the pass that already builds the card, and a campaign title is in another directory
|
||||
- **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
|
||||
- **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 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
|
||||
- The campaigns directory is created by `init` and **on demand** by `campaign add`, since every board made before campaigns existed has none and a `worklane init` over a live board to get one would be a strange thing to have to do
|
||||
|
||||
@@ -208,6 +224,21 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **A card's height therefore depends on the column's width**, so `card_lines` and `card_height` both take it. `column_areas` is shared between the draw and `follow_selection` for the same reason: `Ratio` hands the remainder column to whichever slot it likes, and reproducing that arithmetic by hand is how the measurement and the draw come to disagree about where a card starts
|
||||
- **A corner that will not fit is dropped whole**, never truncated or wrapped: half a date reads as a different date, and a card that reflows in a narrow column changes height, which the scroll would then have to chase. The left corner is the ticket's identity and always stays
|
||||
- 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
|
||||
- **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
|
||||
- **`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 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
|
||||
- **`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
|
||||
- **`q` takes off one layer at a time, in the order they were put on**: the overlay, then the campaign filter, then the board. `Board::dismiss` holds all three, and it takes the screen now because clearing the filter reloads and has to follow the selection. Selecting a campaign closes an open ticket, the answer hiding the done column already gives: the ticket may not be on the filtered board at all, and swapping it for a different one without saying so is how a person acts on the wrong ticket
|
||||
- **`digest` watches the campaigns directory** as well as the statuses and the comments. A campaign filed elsewhere has to reach the picker and a codename edited by hand has to reach every card that names it, and a directory's own mtime would miss the edit
|
||||
- **The tags go under the title, dimmed, each prefixed with `#`.** The field was invisible on the board: nothing said a ticket was tagged `bug` without opening it. The marker is what stops the row reading as a third line of the title, since a tag is an ordinary word and the title sits directly above it. The row is dropped whole when the column will not hold it, the rule a corner follows, and an untagged ticket spends no row at all, the way a short title spends no second one
|
||||
- `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
|
||||
@@ -273,6 +304,13 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- `detail_body` closes a line only where the text says, so a part that does not end on a newline runs on into the next one. The seam between text and rows is wherever the body put it rather than wherever a part happened to end
|
||||
- **The relations block is the only coloured part of the overlay body, and that is a decision, not an oversight.** The headings, the plan numbers, the criteria marks, the bold runs and the grey unset values are all painted by `show` and all flat on the board. The block earned its colour because it is where a reader compares several references at once, and because it was already data rather than prose: it arrives as rows for the status mark, so styling it cost nothing extra. Colouring the rest means giving every painted run in `content_parts` the `Cell` treatment, which is a much larger change with no reader's question behind it, and it is its own ticket. Do not paint one more section here without taking that on: two coloured sections and five plain ones reads as a bug, where one clearly does not
|
||||
|
||||
### Finding the Board
|
||||
- **`find_worklane_dir` classifies the entry before it follows it.** `exists()` follows a link, so a `.worklane` that was a dangling symlink answered the same as no `.worklane` at all: the walk carried on up the tree and the first board above the project became the one every write landed in, silently. `classify` reads `symlink_metadata` first and answers one of four, `Absent`, `Board`, `Dangling` or `NotADirectory`, and **`Absent` is the only one the walk carries on from**. A `.worklane` that is there but unusable is this project's board and is reported, not handed upward
|
||||
- Anything other than `NotFound` from `symlink_metadata` is an error rather than an `Absent`. Reading a filesystem that could not answer as nothing-there is how the walk-past worked in the first place
|
||||
- The dangling failure **names the target and says the boards repo may not be cloned**, and deliberately does not say to run `worklane init`. Once the boards live outside the project a dangling link is an ordinary state, what you have before the boards repo is cloned and after a board directory is renamed, so "no board found, run init" points at the wrong problem
|
||||
- **A link that resolves is indistinguishable from a real directory, and what comes back is the link rather than its target.** `.worklane/backlog/*.md` has to read the same either way and nothing downstream learns whether the board is local, which is the property the shared-boards layout rests on
|
||||
- A regular file at that path is an error as well. It is a plausible future pointer form, and reading it as one is that change's decision to make; stepping over it and writing to a board above is the one answer that is wrong today
|
||||
|
||||
### Monitoring Several Boards
|
||||
- `worklane tui <path>...` takes any number of paths, each resolved through `find_worklane_dir` the way the working directory is: the first `.worklane` at or above it. No path is the working directory, so a bare `worklane` and `worklane tui` are unchanged
|
||||
- The failure **names the path** that had no board, since with several arguments "No .worklane directory found" does not say which one was wrong. Only when a path was given: a bare `worklane` has no path to name and keeps the message every other command gives, which is what its integration test asserts
|
||||
@@ -280,7 +318,7 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- **`Tab` owns the selection**, `column`, `card` and `offsets`, not `Board`. Sharing them across projects would point the selection at whatever unrelated ticket sat at the same place in the tab you switched to. `Board::current()` is the tab in view, and `show_done` stays on the board because it is a preference about the flow rather than about a project
|
||||
- The tabs are fixed for the run: a project cannot be added or dropped without restarting, so `Board::new` builds the tab list once and `reload` only refills each tab's columns. `reload` clamps **every** tab, and `select_tab` clamps again on arrival, because done may have been hidden while another tab was in view
|
||||
- The merge tab goes **first** and is where the view opens: it is the reason to monitor several boards at once. It is materialised in `reload`, from the cards already read, rather than computed per draw — the same reason the criteria count is filled in `collect_ticket_items`
|
||||
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. That comparator is exported for this and is the one `collect_ticket_items` uses, so the two orders cannot drift
|
||||
- The merge is **sorted**, through `by_priority_then_title` in `util.rs`, not concatenated. An overview whose order depended on the order of the arguments would bury one project's p1 under another's p5. It keeps priority then title where every other column takes `by_status_order`: the merge spans statuses, so no single entry stamp governs it
|
||||
- `Card` wraps a `TicketItem` with the project it came from, `Some` only on the merge tab. Decided at reload rather than passed down to `card_lines` as a "which tab is this" flag. `TicketItem` is therefore `Clone`: the merge holds a second copy rather than re-reading every tree
|
||||
- **The project follows the id, on the card and on the overlay border.** Across boards the id is not an address: two projects can hold the same title, and seven characters do not say where they live. `project_label` takes what the row has left after the mark and the id and ends in an ellipsis, and it is measured before the due date, so on the merge the project wins the narrow column and the date is what `corner_line` drops
|
||||
- `tab` and `shift+tab` cycle rather than clamp, unlike the cards and columns: a row of tabs is a ring, and there is no end of a list to run off. Both were free of every other binding — the columns took `hjkl` and the arrows
|
||||
@@ -289,13 +327,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
### Shipping the Agent Assets
|
||||
- The skill is embedded with `include_str!` from `assets/SKILL.md`, not copied by an install script. `cargo install` places binaries and nothing else, so an installed document that is not in the binary is a document that drifts from it
|
||||
- **`assets/SKILL.md` is the only worklane skill document in this repo, and nothing may reintroduce a second.** There was one: `.opencode/skill/worklane-kanban-skill/SKILL.md`, 223 lines of the same document that nothing shipped and no test checked, and it drifted exactly as far as a copy nobody reads does. Its frontmatter still called the skill `worklane_kanban`, its examples still used short flags the CLI had stopped accepting, and it knew nothing about `relate`, `campaign`, `chown`, `check` or the four-status flow. It was **not** inert while it existed: `opencode debug skill` listed it, so an agent working in this repo saw two worklane skills and could load either. Deleted by b2c5531. A copy under `.opencode/`, in a second assets file, or in the README is the same mistake; the document has one home and `install-skill` is how it travels
|
||||
- **One install path serves both agents:** `~/.claude/skills/worklane/SKILL.md`. Claude Code reads it, and opencode loads that directory as an external skill source alongside its own `~/.config/opencode/skill/`. Verified against opencode 1.15.10, whose built-in `customize-opencode` skill documents the table and whose `opencode debug skill` lists what it found there. Do not add the second path: it is two copies of one document, free to drift, for no gain
|
||||
- `Asset` carries the content, the path under its root and the word used in messages, so `install-tool` adds an entry and its own root rather than a second copy of the compare-and-refuse logic. That is why the module is `install.rs` and not `skill.rs`
|
||||
- `install()` takes the root as an argument. That is what lets the tests install into a temp directory instead of the home of whoever runs the suite, and the integration test redirects `HOME` for the same reason
|
||||
- **A modified copy is refused, not overwritten.** Someone may have edited it on purpose, and the message names `--print` so it can be diffed and `--force` so it can be replaced. A read error is not treated as absent either: the write reports the real reason
|
||||
- Three tests guard the document rather than the mechanism, and they are the ones that earn their keep: the frontmatter has to parse (both agents silently ignore a document without it), every `worklane <x>` the skill shows has to be a real subcommand, and every subcommand outside `NOT_FOR_AGENTS` has to appear in the skill. The last one catches a new command that nothing tells an agent about
|
||||
- `install-skill` looks for no board. The skill is what teaches an agent worklane, so needing a `.worklane` to install it would put it out of reach exactly when it is wanted
|
||||
- The assets under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question
|
||||
- The **agent files** under `.opencode/` are the user's, not this repo's to ship. Do not embed or install them. `reviewing-agent.md` there is the prior art the review skill grew out of and is deliberately **left in place**: its content is now in `assets/REVIEW.md`, but deleting a file under `.opencode/` is not this repo's call. Whether the stale copies there go is b2c5531's question. The tool file is the exception and no longer lives there: it was `.opencode/tools/worklane.ts`, which meant it existed only inside a checkout, and it is now `assets/TOOL.ts` and shipped like every other asset
|
||||
- **`install-skill` writes every shipped document, and the name narrows it.** One document teaches the CLI and the others teach a job done with it, so a person who learned the invocation before a document existed still receives it. Requiring a name per document would mean a new skill silently never arrives for anyone who does not read the changelog
|
||||
- **`--print` requires the name.** It exists so a modified copy can be diffed, and a diff is against one document; printing them concatenated would be neither of them. The unnamed case errors with the list of names rather than guessing, the same choice the `comment --` body makes
|
||||
- The refusal message names the document it is about, `install-skill worklane --print`, since with several installed "compare with --print" does not say compare what
|
||||
@@ -304,6 +343,14 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- The review skill's own rules are guarded by `the_review_skill_keeps_the_decisions_that_define_it`, because each of them is a line an edit could drop without breaking anything: **the reviewer never ticks a criterion** (a tick is the implementer's claim, unticking is the review disagreeing, and one mark for both loses the disagreement), **never moves the ticket** (`mv` belongs to whoever does the work, the reviewer's half is the recommendation), and **never reviews the working tree when no commit names the ticket** (it says what it searched for and stops, since an untraceable ticket in `reviewing` is itself the finding)
|
||||
- **The plan skill is the one that can do damage, so its rules are the ones under test.** `set --tags` replaces the whole field, so a sweep that restates a ticket's tags incompletely deletes the rest, and a due date is neither validated nor clearable. `the_plan_skill_keeps_the_rules_that_bound_a_sweep` pins propose-then-apply and those two traps, because a document that loses them still reads like a plan
|
||||
- `.opencode/agent/feature-planner-agent.md` is **deliberately not folded into `PLAN.md`**. It decomposes a feature request into new tickets, which is intake; `PLAN.md` orders the tickets that already exist. Merging them would give one document two jobs and a frontmatter description that fits neither, which is the same reason the review skill is its own document
|
||||
- **`install-tool` is a second command, not a flag on `install-skill`, because the two artifacts are not alike.** A skill is inert markdown that any agent can read and it reaches both from one path; the tool is executable TypeScript that reaches opencode alone. Claude Code has no directory it scans for a tool definition at all: `claude mcp add` with a `stdio`, `sse` or `http` transport is the only way a tool enters its tool list, and its plugin system adopts `agents`, `hooks`, `monitors`, `workflows`, `output-styles` and `themes` and nothing named tools. So an MCP server, a different artifact, would be what reached it. Verified against Claude Code 2.1.238
|
||||
- **`tools_root()` follows `XDG_CONFIG_HOME`, `skills_root()` does not.** `~/.claude` is not an XDG path and opencode's config root is: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without. An empty value counts as unset, the convention `colors_wanted` follows for `NO_COLOR`. `opencode_tool_dir` takes both variables as arguments for the reason `colors_wanted` does, since a threaded test binary cannot mutate the process environment to reach one branch at a time
|
||||
- **Singular `tool`, and it was measured, not guessed.** opencode 1.15.10 loads `~/.config/opencode/tool/` and `~/.config/opencode/tools/` both: each was served in turn from a directory outside any project and `/experimental/tool/ids` registered all eleven worklane tools. The singular is the spelling opencode's own documentation puts first, the way it writes `agent(s)` and `skill(s)`. `opencode serve` plus that endpoint is how to check this again; there is no `opencode debug tool` to ask
|
||||
- **`worklane.ts` is the file name the tool ids are built from.** opencode names each tool as the file then the export, so the file's eleven `export const` lines become `worklane_add` through `worklane_uncheck`. Renaming the file renames every tool and every permission rule that mentions one, which is why `TOOL.relative` is pinned by a test rather than left as a detail
|
||||
- **The tool needs nothing installed beside opencode**, which is worth stating because the file is executable and reads as though it wants a toolchain. It is loaded into opencode's own Bun runtime and the `@opencode-ai/plugin` import resolves there: a copy in a project with no `node_modules` anywhere above it registered all eleven tools, on a machine with no `bun` on `PATH`. c092ea7's criterion 6 named those two as runtime requirements and it was wrong about both
|
||||
- **The closing line differs from the skills', and that is not a wording choice.** opencode reads its config once at startup and never reloads it, so a running one keeps the tools it began with; the skills' "on their next session" would be a claim that is not true here
|
||||
- **The wrapper is behind the CLI and nothing guards it.** It has no tool for `relate`, `campaign`, `assign` or `tags`, so an agent holding the tools cannot reach campaigns or relations at all. `every_tool_the_wrapper_exports_is_a_real_subcommand` catches the drift in the direction that breaks at call time, a tool for a command that no longer exists, and deliberately not the reverse: the gap is real, nobody has decided to close it, and a test asserting it would fail on that decision rather than on a mistake
|
||||
- **Installing it globally reproduces fb3dec6 for the wrapper.** Global tools apply in every project including this one, so once `install-tool` has run, an agent working on worklane uses the installed copy of `assets/TOOL.ts` and not the tree it is editing. Same trap as the `worklane` on `PATH`, second instance
|
||||
- `every_agent_facing_subcommand_is_documented` stays on `SKILL` alone. It owns the CLI surface; a role document uses the handful of commands its job needs, and requiring the rest would fill a review document with `init` and campaigns to satisfy a test. The two checks that do run over every document are the frontmatter and that no document shows a command that does not exist
|
||||
|
||||
### Color and Output
|
||||
@@ -327,6 +374,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
- 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
|
||||
- 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
|
||||
- **The palette splits in two: seven colours that each mean one thing, and `TAG_COLORS`, the eight a tag may be drawn in.** A tag in red would read as a uuid, in green as a title, in grey as an unset value, so the tag slots are reserved as a list rather than picked at the call site. Do not assign a new meaning to a colour in `TAG_COLORS`, and do not draw a tag in one outside it
|
||||
- `tag_color()` is a pure function of the tag string, so the same tag is the same colour on every card, in every view and on every board, with nothing stored. Case sensitive, because `Bug` and `bug` are two different tags to the field and to every search
|
||||
- **The hash is FNV-1a written out here, not `DefaultHasher`.** std does not promise its output is stable across releases, and a board that repaints itself on a toolchain upgrade has lost the only property the mapping is for. `the_tag_mapping_is_pinned` fails on any change to it, so a repaint is a decision rather than a surprise
|
||||
@@ -346,7 +395,8 @@ and this file is for what someone changing worklane's own code needs.
|
||||
|
||||
### Ticket Resolution
|
||||
- `resolve_ticket()` returns `(status, title, content)` tuple
|
||||
- Three tiers, evaluated in order: UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the three reported an exact prefix match as ambiguous against whichever title mentioned it
|
||||
- Four tiers, evaluated in order: exact codename > UUID prefix > title substring > filename substring. The first non-empty tier wins outright and later tiers are not consulted. This is not cosmetic: ticket titles reference other tickets by id, so a flat OR of the tiers reported an exact prefix match as ambiguous against whichever title mentioned it
|
||||
- The codename tier is a campaign's, and empty for a ticket, which has no such field. Case insensitive like the other three, so a codename typed back off a listing resolves whatever case it was read in. See Campaigns for why it sits above the uuid prefix
|
||||
- The UUID tier applies from `MIN_ID_SEARCH` (4) characters up. Not 8: `ls` prints `SHORT_ID_WIDTH` (7) characters, so a longer minimum would drop the printed id out of the UUID tier and let any title quoting it win instead. Below the minimum the search is text, so `show 641` is a title search
|
||||
- The filename tier earns its place by reaching the middle of a UUID, which the prefix tier cannot. It is also why a short UUID search still resolves under a longer minimum, just at the wrong precedence, so a test for the minimum needs a decoy title to be meaningful
|
||||
- Ambiguous matches (multiple results) print options and exit(1)
|
||||
|
||||
Generated
+1
-1
@@ -1503,7 +1503,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "worklane"
|
||||
version = "0.18.1"
|
||||
version = "0.24.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "worklane"
|
||||
version = "0.18.1"
|
||||
version = "0.24.0"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
@@ -5,11 +5,11 @@ 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, `q` to quit. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane` or `worklane tui [path...]` | Opens the board: four status columns, redrawn when the tree changes. Read only. Opens on backlog, committed and reviewing; `d` shows or hides done, whose count stays in the footer either way. Arrows or `hjkl` to move, `enter` for detail, `pgup`/`pgdn` to scroll an open ticket, whose border carries a page indicator while there is more of it than fits, `/` to jump to the first ticket whose id or title matches, `y` to copy the selected ticket's short id to the clipboard, `c` to pick a campaign and filter the columns to its members, `q` to close whatever is open and then to quit. A card carries its campaign beside its tags, marked `~` and bold; while one is selected a frame above the columns names it and says how far it has got, and `q` on its border gives the whole board back. Each path opens the first `.worklane` at or above it, the working directory by default. Several paths are monitored together, as a tab per project plus an `all` tab that merges them, with `tab` and `shift+tab` between them |
|
||||
| `worklane init` | Creates `.worklane/` with backlog, committed, reviewing, done directories |
|
||||
| `worklane add` | Creates a ticket in backlog with `--title`, `--description`, `--acceptance`, `--plan`, `--tags`, `--due`, `--owner`, `--priority` flags. `--due` takes `YYYY-MM-DD` and refuses anything else at parse time |
|
||||
| `worklane ls [status]` | Lists tickets, sorted by priority then title. Optional positional status, and `--priority <1-5>`, `--tag <tag>` and `--campaign <campaign>`, which compose in any combination. `--tag` matches a whole value of the comma-separated Tags field, case sensitively, so `--tag bug` does not list a ticket tagged `bugfix` or one tagged `Bug`. `--ids` prints one ticket per line as its short id, a tab and its title, unstyled, done included, for a script or a completion |
|
||||
| `worklane show <id>` | Shows ticket by UUID prefix (4+ chars), title substring, or filename substring |
|
||||
| `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 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 |
|
||||
@@ -18,8 +18,15 @@ Worklane is a local Kanban flow for agentic software development.
|
||||
| `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 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 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-tool` | Writes the embedded opencode tool definitions to `$XDG_CONFIG_HOME/opencode/tool/worklane.ts`, or `~/.config/opencode/tool/` without it, where opencode loads them for every project. One file and so no name to pass. `--force` and `--print` behave as they do for a skill. opencode only: it registers the eleven `worklane_*` tools from the file name and its exports, and Claude Code has no directory it scans for a tool definition, so reaching it would mean an MCP server rather than this. Restart opencode after installing, since it reads its config at startup and never reloads it. Nothing else to install: the file runs inside opencode's own runtime, so neither Bun nor `@opencode-ai/plugin` has to be on the machine |
|
||||
|
||||
## Completions
|
||||
|
||||
@@ -39,10 +46,14 @@ worklane mv <TAB> the same, then --status <TAB> for the four
|
||||
worklane chown alice <TAB> the ticket, which is the second argument here
|
||||
worklane chown --clear <TAB> the ticket, which the flag carries here
|
||||
worklane relate x --blocked-by <TAB>
|
||||
worklane campaign show <TAB> the campaigns, from `campaign ls --ids`
|
||||
worklane assign <TAB> the same, since a campaign comes first here
|
||||
worklane ls --campaign <TAB> and again
|
||||
worklane ls --tag <TAB> the tags, from `worklane tags`, with their counts
|
||||
```
|
||||
|
||||
The tickets come from `worklane ls --ids`, one run per keypress, 2.5ms in release on a board of
|
||||
seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the
|
||||
The tickets come from `worklane ls --ids`, the campaigns from `worklane campaign ls --ids` and the tags
|
||||
from `worklane tags`, one run per keypress, 2.5ms in release on a board of seventy-five tickets. Since fish runs whatever `worklane` is on PATH, **completions need the
|
||||
installed binary to be current**: an older one without `--ids` completes nothing. Re-run
|
||||
`cargo install --path .` after pulling.
|
||||
|
||||
|
||||
+24
-10
@@ -58,16 +58,17 @@ worklane ls # every status, counts then tickets
|
||||
worklane ls backlog # one status
|
||||
worklane ls --priority 1 # the top of the pile
|
||||
worklane ls --tag bug # one tag's worth of the board
|
||||
worklane tags # the whole vocabulary, with counts
|
||||
worklane show 1b78a24 # one ticket, with its relations and comments
|
||||
worklane campaign ls # the goals that already exist
|
||||
```
|
||||
|
||||
`ls` prints the mark, the id, the title, the owner and the due date. It does **not**
|
||||
print tags, so the vocabulary itself still has to be read off the tickets: `--tag` answers
|
||||
"what is tagged `bug`" and cannot answer "what tags exist", which is the question a
|
||||
grooming sweep starts from. Count the vocabulary with a `show` per ticket, then use
|
||||
`--tag` to check each candidate, and remember that `--tag` matches whole values case
|
||||
sensitively: `bug` and `Bug` are two answers, which is exactly the split worth reporting.
|
||||
`ls` prints the mark, the id, the title, the owner and the due date, and **not** the tags.
|
||||
So the vocabulary comes from `worklane tags`, which is the one command that answers what
|
||||
tags exist rather than what carries a tag you already know. One line per tag, alphabetical,
|
||||
as the tag, a tab and its count. It is case sensitive like the filter, so `bug` and `Bug`
|
||||
list separately and, being alphabetical, land next to each other, which is where a
|
||||
near-duplicate is spotted. Start a tag sweep there rather than with a `show` per ticket.
|
||||
|
||||
Read `done` too when the question is about what to do next. What was finished last is the
|
||||
best evidence of what this board actually moves at, and a plan that ignores it is a wish.
|
||||
@@ -131,7 +132,11 @@ field**. Restate every tag the ticket should keep, or the ones you left out are
|
||||
This is the single most destructive thing in this document. `--clear tags` empties the
|
||||
field on purpose, which is a different thing from emptying it by forgetting a tag.
|
||||
|
||||
Derive the vocabulary from the board rather than inventing one. Read the tickets, count
|
||||
`worklane tags` before and after a tag sweep is the cheapest check that it did what was
|
||||
proposed: a count that dropped where nothing was meant to change is a tag lost to the
|
||||
replace-the-whole-field rule above.
|
||||
|
||||
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:
|
||||
|
||||
- **Two spellings of one idea.** `bug` and `bugfix`, `tui` and `ui`. Pick the one already
|
||||
@@ -153,9 +158,10 @@ fields; a goal is a campaign.
|
||||
|
||||
```
|
||||
worklane campaign ls
|
||||
worklane campaign show "v1 release"
|
||||
worklane campaign add --title "..." --description "..."
|
||||
worklane assign "v1 release" 1b78a24
|
||||
worklane campaign show v1
|
||||
worklane campaign add --title "..." --codename v1 --description "..."
|
||||
worklane campaign set v1 --title "..." # or --codename, on one already filed
|
||||
worklane assign v1 1b78a24
|
||||
```
|
||||
|
||||
A campaign is the tickets that have to be finished **together** for one outcome. The test
|
||||
@@ -172,6 +178,14 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag.
|
||||
- **A campaign's state is derived**, open until every member is done. There is nothing to
|
||||
close and nothing to move. A campaign whose members are all done is finished already.
|
||||
- `assign` takes the **campaign first and the ticket second**, like `chown`.
|
||||
- **Propose a codename with the campaign**, one word, `v1` or `beaver`. It is what the
|
||||
board draws on every card in it and the shortest thing that addresses it at the command
|
||||
line, and a campaign filed without one is drawn by its short id, which says nothing. A
|
||||
campaign already on the board that has no codename is worth pointing out for the same
|
||||
reason a near-duplicate tag is, and `campaign set` is how it gets one without refiling.
|
||||
- **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.
|
||||
|
||||
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.
|
||||
|
||||
+31
-7
@@ -65,6 +65,12 @@ against the whole values of the comma-separated `Tags` field, case sensitively,
|
||||
tags matches none. A tag nothing carries lists nothing rather than failing, so when a
|
||||
listing comes back empty check the spelling against a ticket you know is tagged.
|
||||
|
||||
`worklane tags` answers the other question, the one `--tag` cannot: **what tags exist**.
|
||||
One line per tag, alphabetical, as the tag, a tab and how many tickets carry it. Case
|
||||
sensitive, like the filter, so `bug` and `Bug` list separately and land next to each
|
||||
other, which is where a near-duplicate is spotted. Read it before inventing a tag, and
|
||||
read it when a `--tag` filter comes back emptier than expected.
|
||||
|
||||
## Working a ticket
|
||||
|
||||
```
|
||||
@@ -200,14 +206,30 @@ status directory. Its state is derived instead, open until every member is done,
|
||||
there is no such thing as a done campaign holding an open ticket.
|
||||
|
||||
```
|
||||
worklane campaign add --title "v1 release" \
|
||||
worklane campaign add --title "First public release" --codename v1 \
|
||||
--description "Everything that has to ship before the tag."
|
||||
worklane campaign ls # every campaign and how far it has got
|
||||
worklane campaign show "v1 release" # its body, then its members by status
|
||||
worklane assign "v1 release" 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign "v1 release" # only that campaign's tickets
|
||||
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 assign v1 1b78a24 # put a ticket in it
|
||||
worklane ls --campaign v1 # only that campaign's tickets
|
||||
```
|
||||
|
||||
**Give a campaign a `--codename`.** One word, `v1` or `beaver`. It is what the board
|
||||
draws on every card in the campaign, because a uuid does not fit there and a title is a
|
||||
sentence, and it is the shortest thing that addresses the campaign at the command line.
|
||||
Optional: a campaign without one is drawn and listed by its short id instead, which
|
||||
resolves but says nothing. `campaign set <campaign> --codename <word>` gives one to a
|
||||
campaign that is already filed, which is what every campaign filed before the field
|
||||
existed needs. **Replacing a codename it already has needs `--force`**: that word is how
|
||||
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.
|
||||
|
||||
`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
|
||||
has one writer the way owner and status do.
|
||||
@@ -220,8 +242,10 @@ reports no change and writes nothing.
|
||||
its listing: a campaign is precisely the question of what is finished against what is
|
||||
left.
|
||||
|
||||
A campaign is addressed the way a ticket is, by uuid prefix, title or filename, but it
|
||||
is not a ticket. Passing one where a ticket is expected is refused with a message saying
|
||||
A campaign is addressed the way a ticket is, by uuid prefix, title or filename, and by
|
||||
its exact codename, which wins over all three. So `assign v1 1b78a24` reaches the
|
||||
campaign codenamed `v1` even if another campaign's title contains `v1`. It is not a
|
||||
ticket, though. Passing one where a ticket is expected is refused with a message saying
|
||||
so, and there is no way to move a campaign, because it has no status to move.
|
||||
|
||||
## Search the backlog before filing
|
||||
|
||||
+36
-10
@@ -41,6 +41,12 @@ pub fn ensure_campaigns_dir(worklane_dir: &Path) -> Result<PathBuf> {
|
||||
pub struct Campaign {
|
||||
pub uuid: String,
|
||||
pub title: String,
|
||||
/// The word the campaign is called by, or `None` for one filed without a codename.
|
||||
///
|
||||
/// Read here rather than parsed at each call site for the reason the title is: the
|
||||
/// board draws it on every card that names this campaign, and the picker draws it on
|
||||
/// every row, so it comes off the one read of the directory.
|
||||
pub codename: Option<String>,
|
||||
pub content: String,
|
||||
}
|
||||
|
||||
@@ -80,6 +86,7 @@ pub fn resolve_campaign(search: &str, worklane_dir: &Path) -> Result<Campaign> {
|
||||
}
|
||||
|
||||
Ok(Campaign {
|
||||
codename: parse_codename(&found.content),
|
||||
uuid,
|
||||
title: found.title,
|
||||
content: found.content,
|
||||
@@ -103,6 +110,11 @@ pub fn campaign_named(search: &str, worklane_dir: &Path) -> Option<String> {
|
||||
/// One pass for the same reason [`RelationIndex`] takes one: rendering a ticket's
|
||||
/// Campaign field or listing the campaigns both need every one of them, and a lookup
|
||||
/// per ticket would read the directory once per row.
|
||||
///
|
||||
/// `Default` is the empty index, which is what a board whose campaigns directory cannot be
|
||||
/// read has: it still draws, with no campaign on any card. A *missing* directory is already
|
||||
/// not an error, per [`CampaignIndex::load`]; this is for the unreadable one.
|
||||
#[derive(Default)]
|
||||
pub struct CampaignIndex {
|
||||
campaigns: Vec<Campaign>,
|
||||
}
|
||||
@@ -130,6 +142,7 @@ impl CampaignIndex {
|
||||
campaigns.push(Campaign {
|
||||
uuid: parse_ticket_field(&content, "ID"),
|
||||
title: heading_title(&content),
|
||||
codename: parse_codename(&content),
|
||||
content,
|
||||
});
|
||||
}
|
||||
@@ -188,20 +201,23 @@ pub fn resolved_for(content: &str, worklane_dir: &Path, colored: bool) -> Result
|
||||
pub fn members(worklane_dir: &Path, uuid: &str) -> Result<Vec<(&'static str, Vec<TicketItem>)>> {
|
||||
let mut grouped = Vec::new();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
// Over `Status::ALL` rather than the names, so each group can be put in its own
|
||||
// column's order: a campaign's committed list answers what has waited longest for
|
||||
// the same reason the board's column does.
|
||||
for status in Status::ALL {
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
let items = match status_path.exists() {
|
||||
true => collect_ticket_items(&status_path)?,
|
||||
false => Vec::new(),
|
||||
};
|
||||
|
||||
grouped.push((
|
||||
status,
|
||||
items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect(),
|
||||
));
|
||||
let mut members: Vec<TicketItem> = items
|
||||
.into_iter()
|
||||
.filter(|item| item.campaign.as_deref() == Some(uuid))
|
||||
.collect();
|
||||
members.sort_by(|a, b| by_status_order(status, a, b));
|
||||
|
||||
grouped.push((status.as_str(), members));
|
||||
}
|
||||
|
||||
Ok(grouped)
|
||||
@@ -250,6 +266,9 @@ impl Standing {
|
||||
|
||||
/// The campaign file as it is written.
|
||||
///
|
||||
/// The codename sits directly under the ID, because that is what it is: a second way to
|
||||
/// say which campaign this is, in a word rather than in thirty-six characters.
|
||||
///
|
||||
/// The same shape a ticket has, minus what a campaign has no use for: no acceptance
|
||||
/// criteria, because its definition of done is derived from its members rather than
|
||||
/// written down, no implementation plan, and no Status, because it sits in no status
|
||||
@@ -258,6 +277,7 @@ impl Standing {
|
||||
pub fn campaign_body(
|
||||
title: &str,
|
||||
description: &[String],
|
||||
codename: Option<&str>,
|
||||
id: &uuid::Uuid,
|
||||
owner: Option<&str>,
|
||||
created_at: &str,
|
||||
@@ -279,11 +299,17 @@ pub fn campaign_body(
|
||||
{metadata_heading}\n\
|
||||
\n\
|
||||
- **ID**: {id}\n\
|
||||
- **{codename_field}**: {codename}\n\
|
||||
- **Owner**: {owner}\n\
|
||||
- **Created At**: {created_at}\n\
|
||||
",
|
||||
description_heading = DESCRIPTION.heading,
|
||||
metadata_heading = METADATA_HEADING,
|
||||
owner = owner.unwrap_or("_Not set_"),
|
||||
codename_field = CODENAME_FIELD,
|
||||
// Written unset rather than left out, the way `add` writes an unset Due on every
|
||||
// ticket: the line is then there to read and there to edit by hand, and one shape
|
||||
// of file is one thing for the parser to be right about.
|
||||
codename = codename.unwrap_or(NOT_SET),
|
||||
owner = owner.unwrap_or(NOT_SET),
|
||||
)
|
||||
}
|
||||
|
||||
+138
-3
@@ -109,6 +109,27 @@ fn iso_date(raw: &str) -> Result<String, String> {
|
||||
Ok(raw.to_string())
|
||||
}
|
||||
|
||||
/// Reject a codename that is not one word.
|
||||
///
|
||||
/// At parse time, like `iso_date` and `priority_level`, so a mistyped value is a usage
|
||||
/// error with nothing written. One word because the board draws it as a label beside the
|
||||
/// tags, with a mark and no quoting: `~beaver release` on that row reads as two labels, and
|
||||
/// the second one is not a campaign. A title is where a sentence goes.
|
||||
///
|
||||
/// Nothing else is checked. There is no registry of codenames to check against, the same
|
||||
/// reason `ls --tag` refuses to validate a tag, and a length limit would be a number
|
||||
/// invented here: a label the column will not hold is dropped whole by the row that draws
|
||||
/// it.
|
||||
fn codename(raw: &str) -> Result<String, String> {
|
||||
let value = non_empty(raw)?;
|
||||
|
||||
if value.split_whitespace().count() > 1 {
|
||||
return Err("codename must be a single word, for example v1 or beaver".to_string());
|
||||
}
|
||||
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
/// Arguments that carry prose, and therefore have to accept a value starting with
|
||||
/// a hyphen.
|
||||
///
|
||||
@@ -223,6 +244,16 @@ pub enum Command {
|
||||
ticket: String,
|
||||
},
|
||||
|
||||
/// List the tags the board carries, and how many tickets carry each
|
||||
///
|
||||
/// A command rather than a mode on `ls`, for two reasons. `ls --tag <tag>` answers
|
||||
/// "what is tagged bug" and cannot answer "what tags exist", which is the question a
|
||||
/// grooming sweep starts from; and a `--tags` beside a `--tag` is one letter away from
|
||||
/// a filter that means something else.
|
||||
///
|
||||
/// The output is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
||||
Tags,
|
||||
|
||||
/// Print a shell completion script
|
||||
///
|
||||
/// The structure comes from the clap definition, so a flag added here appears
|
||||
@@ -250,20 +281,58 @@ pub enum Command {
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
|
||||
/// Install the opencode tool definitions that wrap the worklane CLI
|
||||
///
|
||||
/// One artifact, so no name to pass where `install-skill` takes an optional one:
|
||||
/// `--print` here can only mean the one file. opencode alone, and globally, so the
|
||||
/// tools are there in every project rather than in a checkout that happens to carry
|
||||
/// them. Claude Code has no directory it scans for a tool definition; reaching it
|
||||
/// would mean an MCP server, which is not this file.
|
||||
InstallTool {
|
||||
/// Overwrite an existing copy that has been modified
|
||||
#[arg(long)]
|
||||
force: bool,
|
||||
|
||||
/// Write it to stdout instead of installing it
|
||||
#[arg(long)]
|
||||
print: bool,
|
||||
},
|
||||
}
|
||||
|
||||
/// What a campaign can be asked for.
|
||||
///
|
||||
/// No `mv`: a campaign has no status to move it to, its state is derived from its
|
||||
/// members. No `set` or `append` either, which is a gap rather than a decision, since
|
||||
/// nothing yet edits a campaign after it is filed.
|
||||
/// 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.
|
||||
#[derive(clap::Subcommand)]
|
||||
pub enum CampaignCommand {
|
||||
/// File a new campaign
|
||||
Add(CampaignAddArgs),
|
||||
|
||||
/// 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.
|
||||
Set(CampaignSetArgs),
|
||||
|
||||
/// List campaigns with their member counts
|
||||
Ls,
|
||||
Ls {
|
||||
/// Print one campaign per line as its id and title, tab separated, for a script
|
||||
/// or a completion
|
||||
///
|
||||
/// The same flag and the same two fields as `ls --ids`, since it answers the same
|
||||
/// question about a different object. Member counts are left out: counting them
|
||||
/// reads every ticket on the board, and the caller here is a shell filling in a
|
||||
/// candidate list on a keypress
|
||||
#[arg(long)]
|
||||
ids: bool,
|
||||
},
|
||||
|
||||
/// Show a campaign and its members grouped by status
|
||||
Show {
|
||||
@@ -272,6 +341,61 @@ 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`].
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// `--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.
|
||||
///
|
||||
/// 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`].
|
||||
#[derive(clap::Args)]
|
||||
#[command(group(
|
||||
clap::ArgGroup::new("campaign_set_fields")
|
||||
.required(true)
|
||||
.multiple(true)
|
||||
.args(["title", "codename"])
|
||||
))]
|
||||
pub struct CampaignSetArgs {
|
||||
/// Campaign UUID, title, filename or codename
|
||||
pub campaign: String,
|
||||
|
||||
/// Replace the campaign title, renaming the file to match
|
||||
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)]
|
||||
pub title: Option<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
|
||||
/// it was written. Replacing one a campaign already has needs `--force`
|
||||
#[arg(short, long, value_parser = codename)]
|
||||
pub codename: Option<String>,
|
||||
|
||||
/// Replace a codename the campaign already has
|
||||
///
|
||||
/// Without it, `--codename` on a campaign that already has one is refused and nothing
|
||||
/// is written. The codename is how a campaign is referred to once it has one, on every
|
||||
/// card in it and at the command line, so changing it is a decision rather than a
|
||||
/// correction. Setting the codename a campaign already carries is a no-op either way,
|
||||
/// not a refusal: there is nothing to overwrite
|
||||
#[arg(short, long)]
|
||||
pub force: bool,
|
||||
}
|
||||
|
||||
/// What a campaign holds: a title, a description and an owner.
|
||||
///
|
||||
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
|
||||
@@ -279,6 +403,9 @@ pub enum CampaignCommand {
|
||||
/// and no implementation plan. Priority, tags and a due date are left out because
|
||||
/// nothing reads them yet, and a field written but never shown is a field that goes
|
||||
/// stale unnoticed.
|
||||
///
|
||||
/// `--codename` is the exception to that last rule and earns it: the board draws it on
|
||||
/// every card in the campaign, and it exists because the uuid does not fit there.
|
||||
#[derive(clap::Args)]
|
||||
pub struct CampaignAddArgs {
|
||||
/// Campaign title
|
||||
@@ -289,6 +416,14 @@ pub struct CampaignAddArgs {
|
||||
#[arg(short, long, allow_hyphen_values = PROSE)]
|
||||
pub description: Vec<String>,
|
||||
|
||||
/// A single word to call the campaign by, for example v1 or beaver
|
||||
///
|
||||
/// The uuid is what every command stores and the title is a sentence, so neither is
|
||||
/// what a card has room to print. This is the short form the board draws, and it is
|
||||
/// optional: a campaign without one is drawn by its short id instead.
|
||||
#[arg(short, long, value_parser = codename)]
|
||||
pub codename: Option<String>,
|
||||
|
||||
/// Owner. Defaults to the git user
|
||||
#[arg(short, long)]
|
||||
pub owner: Option<String>,
|
||||
|
||||
+236
-21
@@ -42,6 +42,30 @@ pub const TICKET_SECOND_COMMANDS: [&str; 2] = ["chown", "assign"];
|
||||
/// Options whose value is a ticket, as `relate` takes three of.
|
||||
pub const TICKET_FLAGS: [&str; 3] = ["blocked-by", "regression-of", "relates-to"];
|
||||
|
||||
/// Subcommands whose first positional is a campaign.
|
||||
///
|
||||
/// `assign` alone, which takes the campaign first and the ticket second. Kept honest by
|
||||
/// the same test the ticket lists are.
|
||||
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")];
|
||||
|
||||
/// Options whose value is a campaign.
|
||||
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
|
||||
|
||||
/// Options whose value is a tag.
|
||||
///
|
||||
/// Its own list rather than a line in the block below, because the values come from a
|
||||
/// different command: a tag is not an object with an id, so `worklane tags` answers this
|
||||
/// one where `ls --ids` answers the tickets.
|
||||
pub const TAG_FLAGS: [&str; 1] = ["tag"];
|
||||
|
||||
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);
|
||||
@@ -59,11 +83,15 @@ pub fn generate(shell: Shell, out: &mut dyn io::Write) -> io::Result<()> {
|
||||
fn fish_dynamic() -> String {
|
||||
let ticket_commands = TICKET_COMMANDS.join(" ");
|
||||
let ticket_second_commands = TICKET_SECOND_COMMANDS.join(" ");
|
||||
let ticket_flags = TICKET_FLAGS
|
||||
let ticket_flags = flag_list(&TICKET_FLAGS);
|
||||
let campaign_commands = CAMPAIGN_COMMANDS.join(" ");
|
||||
let campaign_nested = CAMPAIGN_NESTED_COMMANDS
|
||||
.iter()
|
||||
.map(|flag| format!("-l {flag}"))
|
||||
.map(|(parent, child)| format!("__worklane_nested_arg_of {parent} {child}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ");
|
||||
.join("; or ");
|
||||
let campaign_flags = flag_list(&CAMPAIGN_FLAGS);
|
||||
let tag_flags = flag_list(&TAG_FLAGS);
|
||||
let statuses = possible_values(Status::value_variants());
|
||||
let shells = possible_values(Shell::value_variants());
|
||||
let skills = SKILLS
|
||||
@@ -87,7 +115,7 @@ complete -c worklane -f
|
||||
# The exception, and the reason the line above is not the whole story: `tui` takes
|
||||
# project paths, as many as you like. Directories only, since each is resolved to the
|
||||
# first `.worklane` at or above it.
|
||||
complete -c worklane -n '__fish_seen_subcommand_from tui' \
|
||||
complete -c worklane -n '__worklane_command_is tui' \
|
||||
-a '(__fish_complete_directories)' -d project
|
||||
|
||||
# Position is counted rather than inferred from what has been typed: matching against
|
||||
@@ -108,6 +136,28 @@ function __worklane_second_arg_of
|
||||
test (count $tokens) -eq 3; and contains -- $tokens[2] $argv
|
||||
end
|
||||
|
||||
# The first argument of a nested subcommand, `worklane campaign show <TAB>`. Three tokens
|
||||
# with both names matched, rather than the token counting the two above do: `campaign show`
|
||||
# puts its argument where a top-level command puts its second, so counting alone would
|
||||
# offer campaigns to `chown alice <TAB>` and tickets here.
|
||||
function __worklane_nested_arg_of
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -eq 3; and test "$tokens[2]" = "$argv[1]"; and test "$tokens[3]" = "$argv[2]"
|
||||
end
|
||||
|
||||
# Which command this is, at any position in it. `$tokens[2]` again rather than
|
||||
# `__fish_seen_subcommand_from`, and for the reason spelled out above: `campaign ls` is an
|
||||
# `ls` that fish has seen, so scoping `--tag` with fish's own helper would offer it under a
|
||||
# command that does not take it.
|
||||
#
|
||||
# A rule carrying `-l` needs one of these. Without it fish takes the option as one the
|
||||
# whole tool accepts, and `worklane init --<TAB>` offered `--blocked-by`, `--tag` and four
|
||||
# others that only `relate` and `ls` have.
|
||||
function __worklane_command_is
|
||||
set -l tokens (commandline -opc)
|
||||
test (count $tokens) -ge 2; and contains -- $tokens[2] $argv
|
||||
end
|
||||
|
||||
# No `-d`: `ls --ids` prints the id and the title separated by a tab, which is fish's
|
||||
# own form for a candidate and its description, so every ticket carries its own.
|
||||
complete -c worklane \
|
||||
@@ -116,12 +166,26 @@ complete -c worklane \
|
||||
|
||||
# `relate` takes its targets as option values, so they are completed by flag rather
|
||||
# than by position.
|
||||
complete -c worklane {ticket_flags} -x -a '(worklane ls --ids)'
|
||||
complete -c worklane -n '__worklane_command_is relate' {ticket_flags} \
|
||||
-x -a '(worklane ls --ids)'
|
||||
|
||||
# Campaigns, from `campaign ls --ids`, in the three places one is named: `assign`'s first
|
||||
# argument, `campaign show`'s only one, and `ls --campaign`.
|
||||
complete -c worklane \
|
||||
-n '__worklane_first_arg_of {campaign_commands}; or {campaign_nested}' \
|
||||
-a '(worklane campaign ls --ids)'
|
||||
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)'
|
||||
|
||||
# `chown --clear` names the ticket in the flag too, since with no user to give there is
|
||||
# no second positional to put it in. Scoped to `chown`, unlike the rule above: `set`
|
||||
# has a `--clear` of its own that takes a field name, and clap already offers those.
|
||||
complete -c worklane -n '__fish_seen_subcommand_from chown' -l clear -x -a '(worklane ls --ids)'
|
||||
complete -c worklane -n '__worklane_command_is chown' -l clear -x -a '(worklane ls --ids)'
|
||||
|
||||
# clap emits the four for `mv --status`, which is an option, but the fish generator
|
||||
# emits nothing for the possible values of a positional. So the one place a status is
|
||||
@@ -136,6 +200,15 @@ complete -c worklane -n '__worklane_first_arg_of install-skill' -a '{skills}' -d
|
||||
)
|
||||
}
|
||||
|
||||
/// Option names as fish wants them on a `complete` line, `-l one -l two`.
|
||||
fn flag_list(flags: &[&str]) -> String {
|
||||
flags
|
||||
.iter()
|
||||
.map(|flag| format!("-l {flag}"))
|
||||
.collect::<Vec<_>>()
|
||||
.join(" ")
|
||||
}
|
||||
|
||||
/// The names a `ValueEnum` accepts, for a fish `-a` list.
|
||||
///
|
||||
/// Read off the enum rather than written out, so a status or a shell added to either one
|
||||
@@ -162,29 +235,68 @@ mod tests {
|
||||
cli
|
||||
}
|
||||
|
||||
/// Every argument in the tool, as the path that reaches it and the argument itself.
|
||||
///
|
||||
/// One walker for the honesty tests below, rather than each one repeating the
|
||||
/// traversal: they differ only in which id they are looking for. Two levels, which is
|
||||
/// as deep as the tool goes, and `help` is skipped because clap generates it and it
|
||||
/// takes no object of ours.
|
||||
fn every_argument() -> Vec<(Vec<String>, clap::Arg)> {
|
||||
let cli = command();
|
||||
let mut found = Vec::new();
|
||||
|
||||
for subcommand in cli.get_subcommands() {
|
||||
let name = subcommand.get_name().to_string();
|
||||
if name == "help" {
|
||||
continue;
|
||||
}
|
||||
for arg in subcommand.get_arguments() {
|
||||
found.push((vec![name.clone()], arg.clone()));
|
||||
}
|
||||
for nested in subcommand.get_subcommands() {
|
||||
let child = nested.get_name().to_string();
|
||||
if child == "help" {
|
||||
continue;
|
||||
}
|
||||
for arg in nested.get_arguments() {
|
||||
found.push((vec![name.clone(), child.clone()], arg.clone()));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
found
|
||||
}
|
||||
|
||||
/// Every subcommand that takes a ticket must be listed, at the position it takes it,
|
||||
/// or it silently loses completion.
|
||||
///
|
||||
/// The nested subcommands are not walked. `campaign` is the only one, none of its
|
||||
/// three takes a ticket, and the token counting above could not tell them apart if
|
||||
/// one did. A ticket argument added under `campaign` needs the fish block reworked,
|
||||
/// not another name in a list.
|
||||
/// Nested subcommands are walked now that `__worklane_nested_arg_of` exists, but
|
||||
/// nothing under `campaign` takes a ticket, so a nested one is a panic rather than a
|
||||
/// list: it would need a rule of its own in the fish block, and a name in a list here
|
||||
/// would look like it already had one.
|
||||
#[test]
|
||||
fn no_ticket_taking_subcommand_is_missing() {
|
||||
for subcommand in command().get_subcommands() {
|
||||
let name = subcommand.get_name();
|
||||
for positional in subcommand.get_positionals() {
|
||||
// `show` calls it `id`; everything else calls it `ticket`.
|
||||
if !matches!(positional.get_id().as_str(), "ticket" | "id") {
|
||||
continue;
|
||||
}
|
||||
match positional.get_index() {
|
||||
for (path, arg) in every_argument() {
|
||||
// `show` calls it `id`; everything else calls it `ticket`.
|
||||
if !matches!(arg.get_id().as_str(), "ticket" | "id") {
|
||||
continue;
|
||||
}
|
||||
let name = path.join(" ");
|
||||
if arg.is_positional() {
|
||||
assert_eq!(
|
||||
path.len(),
|
||||
1,
|
||||
"`worklane {name}` takes a nested ticket argument, \
|
||||
which needs a rule in the fish block"
|
||||
);
|
||||
let top = path[0].as_str();
|
||||
match arg.get_index() {
|
||||
Some(1) => assert!(
|
||||
TICKET_COMMANDS.contains(&name),
|
||||
TICKET_COMMANDS.contains(&top),
|
||||
"`worklane {name}` takes a ticket first but is not in TICKET_COMMANDS"
|
||||
),
|
||||
Some(2) => assert!(
|
||||
TICKET_SECOND_COMMANDS.contains(&name),
|
||||
TICKET_SECOND_COMMANDS.contains(&top),
|
||||
"`worklane {name}` takes a ticket second but is not in \
|
||||
TICKET_SECOND_COMMANDS"
|
||||
),
|
||||
@@ -194,6 +306,97 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// The same for campaigns, which is why the lists above are three rather than one:
|
||||
/// a campaign is named as a first positional, as a nested subcommand's only argument,
|
||||
/// and as an option value, and each needs a different rule in the fish block.
|
||||
#[test]
|
||||
fn no_campaign_taking_argument_is_missing() {
|
||||
let mut seen = 0;
|
||||
for (path, arg) in every_argument() {
|
||||
if arg.get_id().as_str() != "campaign" {
|
||||
continue;
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
|
||||
if let Some(long) = arg.get_long() {
|
||||
assert!(
|
||||
CAMPAIGN_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a campaign but is not in CAMPAIGN_FLAGS"
|
||||
);
|
||||
continue;
|
||||
}
|
||||
|
||||
assert_eq!(
|
||||
arg.get_index(),
|
||||
Some(1),
|
||||
"`worklane {name}` takes a campaign somewhere the fish block has no rule for"
|
||||
);
|
||||
|
||||
match path.as_slice() {
|
||||
[top] => assert!(
|
||||
CAMPAIGN_COMMANDS.contains(&top.as_str()),
|
||||
"`worklane {name}` takes a campaign first but is not in CAMPAIGN_COMMANDS"
|
||||
),
|
||||
[parent, child] => assert!(
|
||||
CAMPAIGN_NESTED_COMMANDS.contains(&(parent.as_str(), child.as_str())),
|
||||
"`worklane {name}` takes a campaign but is not in CAMPAIGN_NESTED_COMMANDS"
|
||||
),
|
||||
_ => panic!("`worklane {name}` is nested deeper than the fish block goes"),
|
||||
}
|
||||
}
|
||||
|
||||
// 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");
|
||||
}
|
||||
|
||||
/// Tags have their own list because their values come from `worklane tags` rather than
|
||||
/// from a listing of objects, so a second tag-taking option would need that rule and
|
||||
/// not the campaign one.
|
||||
#[test]
|
||||
fn no_tag_taking_option_is_missing() {
|
||||
let mut seen = 0;
|
||||
for (path, arg) in every_argument() {
|
||||
if arg.get_id().as_str() != "tag" {
|
||||
continue;
|
||||
}
|
||||
seen += 1;
|
||||
let name = path.join(" ");
|
||||
let long = arg.get_long().unwrap_or_else(|| {
|
||||
panic!(
|
||||
"`worklane {name}` takes a tag as a positional, \
|
||||
which the fish block has no rule for"
|
||||
)
|
||||
});
|
||||
assert!(
|
||||
TAG_FLAGS.contains(&long),
|
||||
"`worklane {name} --{long}` takes a tag but is not in TAG_FLAGS"
|
||||
);
|
||||
}
|
||||
|
||||
assert_eq!(seen, 1, "expected ls --tag");
|
||||
}
|
||||
|
||||
/// **Every rule naming an option has to say which command it belongs to.** A bare
|
||||
/// `complete -c worklane -l tag` tells fish the whole tool takes `--tag`, so
|
||||
/// `worklane init --<TAB>` offered six options that only `relate` and `ls` have. This
|
||||
/// is what stops the next rule being written the same way.
|
||||
#[test]
|
||||
fn every_rule_naming_an_option_is_scoped_to_a_command() {
|
||||
let script = fish_dynamic();
|
||||
// Rules are one logical line, continued with a trailing backslash.
|
||||
for rule in script.replace("\\\n", " ").lines() {
|
||||
if !rule.starts_with("complete") || !rule.contains("-l ") {
|
||||
continue;
|
||||
}
|
||||
assert!(
|
||||
rule.contains("__worklane_command_is"),
|
||||
"this rule declares an option for the whole tool: {rule}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn every_listed_command_is_a_real_subcommand() {
|
||||
let cli = command();
|
||||
@@ -212,7 +415,7 @@ mod tests {
|
||||
.lines()
|
||||
.find(|line| line.starts_with("complete") && line.contains("-l clear"))
|
||||
.expect("chown --clear has a rule of its own");
|
||||
assert!(rule.contains("__fish_seen_subcommand_from chown"), "{rule}");
|
||||
assert!(rule.contains("__worklane_command_is chown"), "{rule}");
|
||||
assert!(rule.contains("worklane ls --ids"), "{rule}");
|
||||
let chown = command().find_subcommand("chown").expect("chown exists").clone();
|
||||
assert!(
|
||||
@@ -256,6 +459,18 @@ mod tests {
|
||||
assert!(script.contains("worklane-review"));
|
||||
}
|
||||
|
||||
/// The two listings the campaign and tag rules read, which are separate commands
|
||||
/// because a campaign has an id and a tag does not.
|
||||
#[test]
|
||||
fn the_fish_script_asks_worklane_for_its_campaigns_and_tags() {
|
||||
let script = fish_dynamic();
|
||||
assert!(script.contains("worklane campaign ls --ids"), "{script}");
|
||||
assert!(script.contains("worklane tags"), "{script}");
|
||||
// The nested position, which neither of the two counting helpers can reach.
|
||||
assert!(script.contains("__worklane_nested_arg_of campaign show"), "{script}");
|
||||
assert!(script.contains("__worklane_first_arg_of assign"), "{script}");
|
||||
}
|
||||
|
||||
/// 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.
|
||||
|
||||
+308
-46
@@ -1,12 +1,14 @@
|
||||
use anyhow::{Result, anyhow};
|
||||
use chrono::Local;
|
||||
use std::collections::BTreeMap;
|
||||
use std::fs;
|
||||
use std::io::{BufRead, IsTerminal, Write};
|
||||
use std::path::Path;
|
||||
|
||||
use crate::campaign::*;
|
||||
use crate::command::{
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CheckArgs, ChownArgs, LsArgs, RelateArgs, SetArgs,
|
||||
AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs,
|
||||
RelateArgs, SetArgs,
|
||||
};
|
||||
use crate::install;
|
||||
use crate::util::*;
|
||||
@@ -61,8 +63,10 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
}
|
||||
|
||||
if let Some(status) = args.status {
|
||||
let status = status.as_str();
|
||||
let status_path = worklane_dir.join(status);
|
||||
// The `Status` is kept alongside its name: the directory is joined from the
|
||||
// name, and the order the column prints in is keyed on the status itself.
|
||||
let name = status.as_str();
|
||||
let status_path = worklane_dir.join(name);
|
||||
if !status_path.exists() {
|
||||
// The status itself is clap's to reject now, so reaching here means the
|
||||
// board is missing a directory it should have rather than that the name was
|
||||
@@ -70,19 +74,20 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
// alone.
|
||||
return Err(anyhow!(
|
||||
"No '{}' directory in {}. Every board has all four; creating it is enough.",
|
||||
status,
|
||||
name,
|
||||
worklane_dir.display()
|
||||
));
|
||||
}
|
||||
|
||||
let items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
|
||||
let mut items = filtered(collect_ticket_items(&status_path)?, priority_filter, uuid, tag);
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
|
||||
if items.is_empty() {
|
||||
println!("No tickets in '{}' status.", status);
|
||||
println!("No tickets in '{}' status.", name);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
println!("Tickets in '{}' status:\n", status);
|
||||
println!("Tickets in '{}' status:\n", name);
|
||||
display_ticket_items(&items);
|
||||
} else {
|
||||
// List all statuses with their ticket counts
|
||||
@@ -99,23 +104,27 @@ pub fn cmd_ls(args: &LsArgs, worklane_dir: &Path) -> Result<()> {
|
||||
println!(" [{}] {} {}", status.to_uppercase(), count, label);
|
||||
}
|
||||
|
||||
// Show all tickets except done grouped by status
|
||||
for status in &statuses {
|
||||
if *status == DONE {
|
||||
// Show all tickets except done grouped by status. Over `Status::ALL` rather
|
||||
// than the names, because each column is ordered by its own entry stamp and the
|
||||
// comparator is keyed on the status, not on the directory it was read from.
|
||||
for status in Status::ALL {
|
||||
if status.as_str() == DONE {
|
||||
continue;
|
||||
}
|
||||
let status_path = worklane_dir.join(status);
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
if !status_path.exists() || !fs::metadata(&status_path)?.is_dir() {
|
||||
continue;
|
||||
}
|
||||
let items = match collect_ticket_items(&status_path) {
|
||||
let mut items = match collect_ticket_items(&status_path) {
|
||||
Ok(items) => filtered(items, priority_filter, uuid, tag),
|
||||
Err(_) => continue,
|
||||
};
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
if items.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let status_header = color_text(&format!("[{}]", status.to_uppercase()), Color::Orange);
|
||||
let status_header =
|
||||
color_text(&format!("[{}]", status.as_str().to_uppercase()), Color::Orange);
|
||||
println!("\n{}", status_header);
|
||||
display_ticket_items(&items);
|
||||
}
|
||||
@@ -148,16 +157,20 @@ fn list_ids(
|
||||
worklane_dir: &Path,
|
||||
) -> Result<()> {
|
||||
let statuses = match status {
|
||||
Some(status) => vec![status.as_str()],
|
||||
None => status_dirs(),
|
||||
Some(status) => vec![status],
|
||||
None => Status::ALL.to_vec(),
|
||||
};
|
||||
|
||||
for status in statuses {
|
||||
let status_path = worklane_dir.join(status);
|
||||
let status_path = worklane_dir.join(status.as_str());
|
||||
if !status_path.exists() {
|
||||
continue;
|
||||
}
|
||||
for item in filtered(collect_ticket_items(&status_path)?, level, campaign, tag) {
|
||||
// The same order the listing prints, so a completion and the board agree on
|
||||
// which ticket is at the head of a column.
|
||||
let mut items = filtered(collect_ticket_items(&status_path)?, level, campaign, tag);
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
for item in items {
|
||||
println!("{}\t{}", item.id, item.title);
|
||||
}
|
||||
}
|
||||
@@ -441,10 +454,19 @@ pub fn cmd_show(search: &str, worklane_dir: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// What is being written, for the messages a failure carries.
|
||||
///
|
||||
/// A `&str` naming the thing rather than two copies of the write path: a campaign file is
|
||||
/// a ticket file in every way that matters here, `<uuid>_<slug>.md` in a directory, and the
|
||||
/// only difference is the word a failure has to use. Every message below puts it
|
||||
/// mid-sentence so there is no capital to case.
|
||||
const TICKET: &str = "ticket";
|
||||
const CAMPAIGN: &str = "campaign";
|
||||
|
||||
/// Write `content` over `path`, without ever leaving half a file behind.
|
||||
///
|
||||
/// Staged in a temp file and renamed into place, because `fs::write` truncates before
|
||||
/// it writes and a partial write would corrupt the ticket. The temp sits under
|
||||
/// it writes and a partial write would corrupt the file. The temp sits under
|
||||
/// `.worklane/` rather than beside the ticket, so a leftover from a hard kill is
|
||||
/// invisible to ticket lookup and to the listing instead of showing up as a stray
|
||||
/// untitled ticket.
|
||||
@@ -453,6 +475,7 @@ fn write_then_replace(
|
||||
path: &Path,
|
||||
filename: &str,
|
||||
content: &str,
|
||||
kind: &str,
|
||||
title: &str,
|
||||
) -> Result<()> {
|
||||
let temp = worklane_dir.join(format!(".wl-{}.tmp", filename));
|
||||
@@ -460,7 +483,8 @@ fn write_then_replace(
|
||||
if let Err(e) = fs::write(&temp, content) {
|
||||
let _ = fs::remove_file(&temp);
|
||||
return Err(anyhow!(
|
||||
"Could not stage the update for ticket '{}' at {}: {}",
|
||||
"Could not stage the update for {} '{}' at {}: {}",
|
||||
kind,
|
||||
title,
|
||||
temp.display(),
|
||||
e
|
||||
@@ -469,21 +493,29 @@ fn write_then_replace(
|
||||
|
||||
if let Err(e) = fs::rename(&temp, path) {
|
||||
let _ = fs::remove_file(&temp);
|
||||
return Err(anyhow!("Could not write ticket '{}' at {}: {}", title, path.display(), e));
|
||||
return Err(anyhow!(
|
||||
"Could not write {} '{}' at {}: {}",
|
||||
kind,
|
||||
title,
|
||||
path.display(),
|
||||
e
|
||||
));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// The ticket file in `dir` carrying `uuid`.
|
||||
/// The file in `dir` carrying `uuid`, ticket or campaign.
|
||||
///
|
||||
/// Matched on the uuid, not the title. Titles are not unique, `add` allows duplicates
|
||||
/// on purpose, so a title scan could land on a different ticket than the one that was
|
||||
/// resolved: `mv <uuid-of-second>` moved the first ticket sharing its title.
|
||||
fn find_ticket_file(dir: &Path, uuid: &str, title: &str) -> Result<String> {
|
||||
/// resolved: `mv <uuid-of-second>` moved the first ticket sharing its title. The same holds
|
||||
/// for a campaign, whose file is named the same way.
|
||||
fn find_entry_file(dir: &Path, kind: &str, uuid: &str, title: &str) -> Result<String> {
|
||||
if uuid.trim().is_empty() || is_unknown_value(uuid) {
|
||||
return Err(anyhow!(
|
||||
"Ticket '{}' has no ID field, so its file cannot be located",
|
||||
"Could not locate the file for {} '{}': it has no ID field",
|
||||
kind,
|
||||
title
|
||||
));
|
||||
}
|
||||
@@ -506,7 +538,8 @@ fn find_ticket_file(dir: &Path, uuid: &str, title: &str) -> Result<String> {
|
||||
}
|
||||
|
||||
Err(anyhow!(
|
||||
"Could not find the file for ticket '{}' in {}",
|
||||
"Could not find the file for {} '{}' in {}",
|
||||
kind,
|
||||
title,
|
||||
dir.display()
|
||||
))
|
||||
@@ -536,7 +569,7 @@ fn move_ticket_file(
|
||||
let source = from.join(filename);
|
||||
let dest = to.join(filename);
|
||||
|
||||
write_then_replace(worklane_dir, &source, filename, content, title)?;
|
||||
write_then_replace(worklane_dir, &source, filename, content, TICKET, title)?;
|
||||
|
||||
// The content is correct and in one place by now, so a failure here leaves the
|
||||
// ticket where it started rather than half moved.
|
||||
@@ -659,7 +692,7 @@ pub fn cmd_mv(ticket_id: &str, target: Status, force: bool, start: &Path) -> Res
|
||||
)?;
|
||||
|
||||
let found_filename =
|
||||
find_ticket_file(¤t_path, &parse_ticket_field(&resolved, "ID"), &title)?;
|
||||
find_entry_file(¤t_path, TICKET, &parse_ticket_field(&resolved, "ID"), &title)?;
|
||||
|
||||
move_ticket_file(
|
||||
&worklane_dir,
|
||||
@@ -755,21 +788,56 @@ fn save_ticket(
|
||||
new_title: Option<&String>,
|
||||
content: &str,
|
||||
) -> Result<()> {
|
||||
let status_path = worklane_dir.join(status);
|
||||
let filename = find_ticket_file(&status_path, uuid, title)?;
|
||||
let path = status_path.join(&filename);
|
||||
let dir = worklane_dir.join(status);
|
||||
save_entry(worklane_dir, &dir, TICKET, uuid, title, new_title, content)
|
||||
}
|
||||
|
||||
write_then_replace(worklane_dir, &path, &filename, content, title)?;
|
||||
/// The same for a campaign, whose directory is `campaigns/` and which sits in no status.
|
||||
///
|
||||
/// A named wrapper rather than a `save_entry` at the call site, so the campaign handler
|
||||
/// reads the way the ticket handlers do and neither has to know which directory the other
|
||||
/// writes to.
|
||||
fn save_campaign(
|
||||
worklane_dir: &Path,
|
||||
uuid: &str,
|
||||
title: &str,
|
||||
new_title: Option<&String>,
|
||||
content: &str,
|
||||
) -> Result<()> {
|
||||
let dir = campaigns_dir(worklane_dir);
|
||||
save_entry(worklane_dir, &dir, CAMPAIGN, uuid, title, new_title, content)
|
||||
}
|
||||
|
||||
// The uuid is kept, so the new name cannot collide with another ticket, and an
|
||||
/// Write a file back where it was, renaming it when the title changed.
|
||||
///
|
||||
/// One body for tickets and campaigns. Both are `<uuid>_<slug>.md` in a directory, both are
|
||||
/// written through `write_then_replace` so a failure leaves no half file, and both rename
|
||||
/// only after the write has landed: renaming first and writing second is what leaves a file
|
||||
/// under a name that does not match what is in it.
|
||||
fn save_entry(
|
||||
worklane_dir: &Path,
|
||||
dir: &Path,
|
||||
kind: &str,
|
||||
uuid: &str,
|
||||
title: &str,
|
||||
new_title: Option<&String>,
|
||||
content: &str,
|
||||
) -> Result<()> {
|
||||
let filename = find_entry_file(dir, kind, uuid, title)?;
|
||||
let path = dir.join(&filename);
|
||||
|
||||
write_then_replace(worklane_dir, &path, &filename, content, kind, title)?;
|
||||
|
||||
// The uuid is kept, so the new name cannot collide with another entry, and an
|
||||
// unchanged slug means there is nothing to rename.
|
||||
if let Some(new_title) = new_title {
|
||||
let renamed = format!("{}_{}.md", uuid, slug(new_title));
|
||||
if renamed != filename {
|
||||
let destination = status_path.join(&renamed);
|
||||
let destination = dir.join(&renamed);
|
||||
fs::rename(&path, &destination).map_err(|e| {
|
||||
anyhow!(
|
||||
"Ticket '{}' was updated but could not be renamed to {}: {}",
|
||||
"Could not rename {} '{}' to {} after updating it: {}",
|
||||
kind,
|
||||
title,
|
||||
destination.display(),
|
||||
e
|
||||
@@ -1036,7 +1104,12 @@ pub fn cmd_relate(args: &RelateArgs, start: &Path) -> Result<()> {
|
||||
/// half-written campaign behind. `cmd_add` predates that primitive and still uses the
|
||||
/// plain write; the difference is noted on the ticket rather than fixed here.
|
||||
pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
|
||||
let CampaignAddArgs { title, description, owner } = args;
|
||||
let CampaignAddArgs {
|
||||
title,
|
||||
description,
|
||||
codename,
|
||||
owner,
|
||||
} = args;
|
||||
|
||||
let worklane_dir = find_worklane_dir(start)?;
|
||||
let dir = ensure_campaigns_dir(&worklane_dir)?;
|
||||
@@ -1053,12 +1126,13 @@ pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
|
||||
let body = campaign_body(
|
||||
title,
|
||||
description,
|
||||
codename.as_deref(),
|
||||
&id,
|
||||
owner.as_deref(),
|
||||
&Local::now().format(TIMESTAMP_FORMAT).to_string(),
|
||||
);
|
||||
|
||||
write_then_replace(&worklane_dir, &path, &filename, &body, title)?;
|
||||
write_then_replace(&worklane_dir, &path, &filename, &body, CAMPAIGN, title)?;
|
||||
|
||||
println!("Created campaign: {}", filename);
|
||||
Ok(())
|
||||
@@ -1070,9 +1144,19 @@ pub fn cmd_campaign_add(args: &CampaignAddArgs, start: &Path) -> Result<()> {
|
||||
/// scan per row rather than one scan reused, and it is deliberate: the alternative is a
|
||||
/// map from campaign uuid to counts built in a single walk, which is worth writing when
|
||||
/// a board has enough campaigns to notice and is premature now.
|
||||
pub fn cmd_campaign_ls(worklane_dir: &Path) -> Result<()> {
|
||||
pub fn cmd_campaign_ls(worklane_dir: &Path, ids: bool) -> Result<()> {
|
||||
let index = CampaignIndex::load(worklane_dir)?;
|
||||
|
||||
// Ahead of the empty check, which prints prose: a completion must offer nothing
|
||||
// rather than offer a sentence, the same bargain `list_ids` takes with a missing
|
||||
// status directory.
|
||||
if ids {
|
||||
for campaign in index.iter() {
|
||||
println!("{}\t{}", short_id(&campaign.uuid), campaign.title);
|
||||
}
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
if index.is_empty() {
|
||||
println!("No campaigns yet. `worklane campaign add --title` files one.");
|
||||
return Ok(());
|
||||
@@ -1088,9 +1172,22 @@ pub fn cmd_campaign_ls(worklane_dir: &Path) -> Result<()> {
|
||||
None => String::new(),
|
||||
};
|
||||
|
||||
// The codename between the id and the title, in the colour the board draws it in
|
||||
// and with the same mark: the answer to "which campaign is this" is one word, and
|
||||
// it should be the same word wherever it is read. A campaign filed without one
|
||||
// spends nothing on it, the way an untagged card spends no row.
|
||||
let codename = match campaign.codename.is_some() {
|
||||
true => {
|
||||
let label = campaign_label(&campaign.uuid, campaign.codename.as_deref());
|
||||
format!("{} ", paint_cells(&[label], colored))
|
||||
}
|
||||
false => String::new(),
|
||||
};
|
||||
|
||||
println!(
|
||||
" ({}) {} | {}{}",
|
||||
" ({}) {}{} | {}{}",
|
||||
paint(short_id(&campaign.uuid), Color::Red, colored),
|
||||
codename,
|
||||
campaign.title,
|
||||
standing.label(),
|
||||
state,
|
||||
@@ -1100,6 +1197,119 @@ pub fn cmd_campaign_ls(worklane_dir: &Path) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Every tag on the board, with how many tickets carry it.
|
||||
///
|
||||
/// 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.
|
||||
///
|
||||
/// **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.
|
||||
pub fn cmd_tags(worklane_dir: &Path) -> Result<()> {
|
||||
// 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();
|
||||
|
||||
for status in status_dirs() {
|
||||
let status_path = worklane_dir.join(status);
|
||||
// Skipped rather than refused, as in `list_ids`, and for the same reason.
|
||||
if !status_path.exists() {
|
||||
continue;
|
||||
}
|
||||
for item in collect_ticket_items(&status_path)? {
|
||||
for tag in item.tags {
|
||||
*counts.entry(tag).or_default() += 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (tag, count) in counts {
|
||||
println!("{}\t{}", tag, count);
|
||||
}
|
||||
|
||||
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,
|
||||
/// `set_metadata_field` for the field, `apply` for whether an edit changed anything, and
|
||||
/// `report` for what it says afterwards. Nothing about writing a field lives twice, which is
|
||||
/// the shape `cmd_chown` already took.
|
||||
///
|
||||
/// The **codename is inserted when the campaign has no such line**, rather than refused.
|
||||
/// `set_metadata_field` refuses a field that is not there, which is right for the fields
|
||||
/// `add` writes; every campaign filed before the field existed has none, and those are
|
||||
/// exactly the campaigns this command is for. So it goes through
|
||||
/// `set_or_insert_metadata_field`, the upsert `assign` already uses for the Campaign field
|
||||
/// on a ticket, for the same reason.
|
||||
///
|
||||
/// **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 changing it out from under that is the same mistake
|
||||
/// overwriting an edited skill document would be. So it is refused, and the refusal names
|
||||
/// both words and the flag, the way `install-skill` names `--force` rather than leaving it
|
||||
/// to be found.
|
||||
///
|
||||
/// Checked before any edit is applied, like `SetArgs::contested`, so a call that also
|
||||
/// carries `--title` writes neither field rather than half of what was asked for.
|
||||
///
|
||||
/// 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.
|
||||
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)?;
|
||||
let title = campaign.title.clone();
|
||||
|
||||
let overwrite = match (&args.codename, &campaign.codename) {
|
||||
(Some(wanted), Some(held)) if wanted != held => Some((held, wanted)),
|
||||
_ => None,
|
||||
};
|
||||
if let Some((held, wanted)) = overwrite.filter(|_| !args.force) {
|
||||
return Err(anyhow!(
|
||||
"Campaign '{}' is already codenamed '{}', so nothing was written. \
|
||||
Pass --force to replace it with '{}'",
|
||||
title,
|
||||
held,
|
||||
wanted
|
||||
));
|
||||
}
|
||||
|
||||
let mut content = campaign.content.clone();
|
||||
let mut changed: Vec<&str> = Vec::new();
|
||||
|
||||
if let Some(new_title) = &args.title {
|
||||
let next = set_title(&content, new_title)?;
|
||||
apply(&mut content, &mut changed, "title", 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);
|
||||
}
|
||||
|
||||
if changed.is_empty() {
|
||||
report(&[], &title, "Updated");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let renamed = changed.contains(&"title").then_some(()).and(args.title.as_ref());
|
||||
save_campaign(&worklane_dir, &campaign.uuid, &title, renamed, &content)?;
|
||||
|
||||
report(&changed, args.title.as_ref().unwrap_or(&title), "Updated");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Show a campaign, then its members grouped by status.
|
||||
///
|
||||
/// Every status is shown, done included, unlike `ls`, which leaves done out of its
|
||||
@@ -1352,9 +1562,38 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
|
||||
};
|
||||
|
||||
let root = install::skills_root()?;
|
||||
let written = install_each(&chosen, &root, force, |asset| {
|
||||
format!("worklane install-skill {} --print", asset.name)
|
||||
})?;
|
||||
|
||||
// Once, and only when something arrived: repeating it per document would make the
|
||||
// instruction look like part of each outcome rather than the one thing to do next.
|
||||
if written {
|
||||
println!("Claude Code and opencode pick it up on their next session");
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Write each asset under `root` and report what happened to it.
|
||||
///
|
||||
/// Shared by both install commands, which differ in what they install and in what they
|
||||
/// say afterwards, never in how an outcome is reported. `compare` is the invocation the
|
||||
/// refusal points at, which is the one line that has to name the command it came from.
|
||||
///
|
||||
/// Returns whether anything was written, because that is what decides the closing line:
|
||||
/// each command has its own thing to say about what picks the asset up, and neither
|
||||
/// should say it once per asset.
|
||||
fn install_each(
|
||||
chosen: &[&install::Asset],
|
||||
root: &Path,
|
||||
force: bool,
|
||||
compare: impl Fn(&install::Asset) -> String,
|
||||
) -> Result<bool> {
|
||||
let mut written = false;
|
||||
|
||||
for asset in chosen {
|
||||
match asset.install(&root, force)? {
|
||||
match asset.install(root, force)? {
|
||||
install::Outcome::Written(path) => {
|
||||
println!("Installed the {} {} to: {}", asset.name, asset.what, path.display());
|
||||
written = true;
|
||||
@@ -1364,18 +1603,41 @@ pub fn cmd_install_skill(skill: Option<&str>, force: bool, print: bool) -> Resul
|
||||
}
|
||||
install::Outcome::Refused(path) => {
|
||||
println!("Differs from the version in this binary: {}", path.display());
|
||||
println!(
|
||||
"Compare with `worklane install-skill {} --print`, or overwrite with --force",
|
||||
asset.name
|
||||
);
|
||||
println!("Compare with `{}`, or overwrite with --force", compare(asset));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Once, and only when something arrived: repeating it per document would make the
|
||||
// instruction look like part of each outcome rather than the one thing to do next.
|
||||
Ok(written)
|
||||
}
|
||||
|
||||
/// Install the opencode tool definitions.
|
||||
///
|
||||
/// No name argument, where `install-skill` has an optional one: there is a single tool
|
||||
/// file, so a name could only be right or wrong, and `--print` needs no help deciding
|
||||
/// what to print.
|
||||
pub fn cmd_install_tool(force: bool, print: bool) -> Result<()> {
|
||||
if print {
|
||||
print!("{}", install::TOOL.content);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let chosen: Vec<&install::Asset> = install::TOOLS.iter().collect();
|
||||
let root = install::tools_root()?;
|
||||
let written =
|
||||
install_each(&chosen, &root, force, |_| "worklane install-tool --print".to_string())?;
|
||||
|
||||
// Not "on its next session", which is what the skills say: opencode reads its config
|
||||
// once at startup and does not reload it, so a running one keeps the tools it began
|
||||
// with. The second line is there because the file is executable and looks like it
|
||||
// needs a toolchain: it does not, it runs inside opencode.
|
||||
if written {
|
||||
println!("Claude Code and opencode pick it up on their next session");
|
||||
println!(
|
||||
"opencode loads it in every project. Restart it: the config is read at startup and never reloaded"
|
||||
);
|
||||
println!(
|
||||
"Nothing else to install. It runs in opencode's own runtime, so neither Bun nor @opencode-ai/plugin is needed on this machine"
|
||||
);
|
||||
}
|
||||
|
||||
Ok(())
|
||||
|
||||
+151
-4
@@ -11,9 +11,11 @@
|
||||
//! has learned the invocation should not have to learn a new name for each document
|
||||
//! added later, or the new one silently never arrives.
|
||||
//!
|
||||
//! The machinery is written once for both kinds of asset this repo will ship. The tool
|
||||
//! file for opencode is executable code needing Bun, so it gets its own command and its
|
||||
//! own root, but the compare-and-refuse logic is the same and lives here.
|
||||
//! The machinery is written once for both kinds of asset. The tool file is executable
|
||||
//! code and reaches opencode alone, so it gets its own command and its own root, but the
|
||||
//! compare-and-refuse logic is the same and lives here. What it needs at runtime is
|
||||
//! opencode and nothing else: it is loaded into opencode's own runtime, so neither Bun
|
||||
//! nor `@opencode-ai/plugin` has to be installed for the import in it to resolve.
|
||||
|
||||
use std::io;
|
||||
use std::path::{Path, PathBuf};
|
||||
@@ -73,6 +75,33 @@ pub const PLAN_SKILL: Asset = Asset {
|
||||
/// statement that took it: a `const` is inlined at each use and the borrow dies there.
|
||||
pub static SKILLS: [Asset; 3] = [SKILL, REVIEW_SKILL, PLAN_SKILL];
|
||||
|
||||
/// The opencode tool definitions, the second kind of asset this binary carries.
|
||||
///
|
||||
/// Executable TypeScript rather than a document, and it reaches one agent where a skill
|
||||
/// reaches both: opencode loads a `.ts` file from its tool directory and Claude Code has
|
||||
/// no directory it scans for one, so this is not the artifact that would reach it. That
|
||||
/// asymmetry is the whole reason it is its own command with its own root rather than a
|
||||
/// flag on `install-skill`.
|
||||
///
|
||||
/// Flat in the root rather than in a directory of its own, and the file name is load
|
||||
/// bearing: opencode builds each tool id as the file name then the export, so this file
|
||||
/// is what makes them `worklane_add` and `worklane_mv` rather than `tool_add`. A skill
|
||||
/// carries the equivalent in its frontmatter `name:`, which its directory has to agree
|
||||
/// with; a tool carries it in the file name alone.
|
||||
pub const TOOL: Asset = Asset {
|
||||
name: "worklane",
|
||||
what: "tool",
|
||||
relative: "worklane.ts",
|
||||
content: include_str!("../assets/TOOL.ts"),
|
||||
};
|
||||
|
||||
/// Every tool this binary carries.
|
||||
///
|
||||
/// One, and an array anyway: it is what keeps the install loop the same shape as the
|
||||
/// skills', so a second tool needs no new machinery. A `static` for the reason `SKILLS`
|
||||
/// is one.
|
||||
pub static TOOLS: [Asset; 1] = [TOOL];
|
||||
|
||||
/// The skill a name on the command line asks for.
|
||||
pub fn skill_named(name: &str) -> Result<&'static Asset> {
|
||||
SKILLS
|
||||
@@ -106,6 +135,48 @@ pub fn skills_root() -> Result<PathBuf> {
|
||||
Ok(Path::new(&home).join(".claude/skills"))
|
||||
}
|
||||
|
||||
/// Where the tool has to sit for opencode to load it in every project.
|
||||
///
|
||||
/// `XDG_CONFIG_HOME` when it is set and non-empty, `~/.config` otherwise, which is what
|
||||
/// opencode itself resolves: `opencode debug paths` reports its config root under
|
||||
/// `$XDG_CONFIG_HOME/opencode` with the variable set and `~/.config/opencode` without.
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows for
|
||||
/// `NO_COLOR`. Checked against opencode 1.15.10.
|
||||
///
|
||||
/// Singular `tool`, though 1.15.10 loads `tools` as well: each was served in turn from a
|
||||
/// directory outside any project and registered all eleven worklane tools. The singular
|
||||
/// is the spelling opencode's own documentation puts first, the way it writes `agent(s)`
|
||||
/// and `skill(s)`.
|
||||
///
|
||||
/// One agent, unlike `skills_root`. Claude Code has no path that belongs here at all: a
|
||||
/// tool reaches it through an MCP server, which is a different artifact and not one this
|
||||
/// binary carries.
|
||||
pub fn tools_root() -> Result<PathBuf> {
|
||||
let xdg = std::env::var_os("XDG_CONFIG_HOME");
|
||||
let home = std::env::var_os("HOME");
|
||||
|
||||
opencode_tool_dir(xdg.as_deref().map(Path::new), home.as_deref().map(Path::new))
|
||||
}
|
||||
|
||||
/// `tools_root` with the two variables passed in rather than read.
|
||||
///
|
||||
/// The seam exists for the reason `colors_wanted` has one: both branches and the failure
|
||||
/// have to be reachable from a test, and a threaded test binary cannot mutate the process
|
||||
/// environment to reach them one at a time.
|
||||
fn opencode_tool_dir(xdg: Option<&Path>, home: Option<&Path>) -> Result<PathBuf> {
|
||||
if let Some(xdg) = xdg.filter(|value| !value.as_os_str().is_empty()) {
|
||||
return Ok(xdg.join("opencode/tool"));
|
||||
}
|
||||
|
||||
let home = home.ok_or_else(|| {
|
||||
anyhow!(
|
||||
"cannot tell where your opencode config lives because neither XDG_CONFIG_HOME nor HOME is set in the environment"
|
||||
)
|
||||
})?;
|
||||
|
||||
Ok(home.join(".config/opencode/tool"))
|
||||
}
|
||||
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
pub enum Outcome {
|
||||
Written(PathBuf),
|
||||
@@ -331,7 +402,7 @@ mod tests {
|
||||
/// Subcommands the skill has no business teaching: the board is interactive and
|
||||
/// belongs to a person, `install-skill` is how the document arrived, and `help`
|
||||
/// is clap's own.
|
||||
const NOT_FOR_AGENTS: [&str; 3] = ["tui", "install-skill", "help"];
|
||||
const NOT_FOR_AGENTS: [&str; 4] = ["tui", "install-skill", "install-tool", "help"];
|
||||
|
||||
/// The converse, and the one that goes stale on its own: a *new* subcommand absent
|
||||
/// from the skill is invisible to an agent, and nothing else would notice.
|
||||
@@ -417,4 +488,80 @@ mod tests {
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------ the tool --
|
||||
|
||||
/// `XDG_CONFIG_HOME` wins, because it is what opencode itself resolves its config
|
||||
/// root from: `opencode debug paths` reports `$XDG_CONFIG_HOME/opencode` with it set.
|
||||
#[test]
|
||||
fn the_tool_root_follows_xdg_config_home_when_it_is_set() {
|
||||
let root = opencode_tool_dir(Some(Path::new("/tmp/xdg")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/tmp/xdg/opencode/tool"));
|
||||
}
|
||||
|
||||
/// An empty value counts as unset, the convention `colors_wanted` already follows, so
|
||||
/// a wrapper script that cleared an inherited one still lands in the home directory
|
||||
/// rather than at `/opencode/tool`.
|
||||
#[test]
|
||||
fn an_empty_xdg_config_home_falls_back_to_the_home_directory() {
|
||||
let root = opencode_tool_dir(Some(Path::new("")), Some(Path::new("/home/x")));
|
||||
assert_eq!(root.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
|
||||
let unset = opencode_tool_dir(None, Some(Path::new("/home/x")));
|
||||
assert_eq!(unset.unwrap(), Path::new("/home/x/.config/opencode/tool"));
|
||||
}
|
||||
|
||||
/// Neither one set is the case that has to fail rather than guess: writing to a
|
||||
/// relative `.config/opencode/tool` would put the tool wherever the caller happened
|
||||
/// to be standing.
|
||||
#[test]
|
||||
fn neither_variable_set_is_an_error_rather_than_a_relative_path() {
|
||||
let error = opencode_tool_dir(None, None).unwrap_err().to_string();
|
||||
assert!(error.contains("XDG_CONFIG_HOME"), "{error}");
|
||||
assert!(error.contains("HOME"), "{error}");
|
||||
}
|
||||
|
||||
/// The file name is the tool id prefix, not decoration: opencode names each tool as
|
||||
/// the file then the export, so a renamed file renames all eleven tools and every
|
||||
/// permission rule that mentions one.
|
||||
#[test]
|
||||
fn the_tool_lands_flat_in_the_root_under_the_name_that_prefixes_its_ids() {
|
||||
let root = opencode_tool_dir(None, Some(Path::new("/home/x"))).unwrap();
|
||||
|
||||
assert_eq!(TOOL.path(&root), Path::new("/home/x/.config/opencode/tool/worklane.ts"));
|
||||
assert_eq!(TOOL.relative, "worklane.ts");
|
||||
}
|
||||
|
||||
/// Every tool the file exports names a real subcommand.
|
||||
///
|
||||
/// The guard the fish completion lists already have, pointed the other way: this
|
||||
/// catches a tool wrapping a command that has been renamed or dropped, which would
|
||||
/// fail only when an agent finally called it. It cannot catch the reverse, a
|
||||
/// subcommand the wrapper never grew a tool for, and the wrapper is behind by
|
||||
/// several: `relate`, `campaign`, `assign` and `tags` have no tool. That is its own
|
||||
/// ticket, and asserting it here would fail on a gap nobody has decided to close.
|
||||
#[test]
|
||||
fn every_tool_the_wrapper_exports_is_a_real_subcommand() {
|
||||
use clap::CommandFactory;
|
||||
|
||||
let commands: Vec<String> = crate::Cli::command()
|
||||
.get_subcommands()
|
||||
.map(|command| command.get_name().to_string())
|
||||
.collect();
|
||||
|
||||
let exported: Vec<&str> = TOOL
|
||||
.content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("export const "))
|
||||
.filter_map(|rest| rest.split_whitespace().next())
|
||||
.collect();
|
||||
|
||||
assert_eq!(exported.len(), 11, "{exported:?}");
|
||||
for name in exported {
|
||||
assert!(
|
||||
commands.iter().any(|command| command == name),
|
||||
"the wrapper exports {name:?}, which is not a subcommand: {commands:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
+24
-3
@@ -67,16 +67,21 @@ fn main() -> Result<()> {
|
||||
}
|
||||
Some(Command::Campaign { command }) => match command {
|
||||
CampaignCommand::Add(args) => cmd_campaign_add(&args, &start),
|
||||
CampaignCommand::Ls => {
|
||||
CampaignCommand::Ls { ids } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_ls(&worklane_dir)
|
||||
cmd_campaign_ls(&worklane_dir, ids)
|
||||
}
|
||||
CampaignCommand::Set(args) => cmd_campaign_set(&args, &start),
|
||||
CampaignCommand::Show { campaign } => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_campaign_show(&campaign, &worklane_dir)
|
||||
}
|
||||
},
|
||||
Some(Command::Assign { campaign, ticket }) => cmd_assign(&campaign, &ticket, &start),
|
||||
Some(Command::Tags) => {
|
||||
let worklane_dir = find_worklane_dir(&start)?;
|
||||
cmd_tags(&worklane_dir)
|
||||
}
|
||||
// No board either, for the reason `install-skill` has none: a completion script
|
||||
// is generated from the clap definition and is the same wherever it is run.
|
||||
Some(Command::Completions { shell }) => {
|
||||
@@ -87,6 +92,9 @@ fn main() -> Result<()> {
|
||||
Some(Command::InstallSkill { skill, force, print }) => {
|
||||
cmd_install_skill(skill.as_deref(), force, print)
|
||||
}
|
||||
// No board either, and one agent rather than both: opencode loads the tool file,
|
||||
// Claude Code has no path for one.
|
||||
Some(Command::InstallTool { force, print }) => cmd_install_tool(force, print),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -173,13 +181,22 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
continue;
|
||||
}
|
||||
|
||||
// The same contract for the campaign picker, which is the other mode that owns
|
||||
// the keyboard while it is open. Two calls rather than one combined pre-branch,
|
||||
// because only one of the two can be open at a time and each reports for
|
||||
// itself; the rules are `Board::search_key` and `Board::picker_key`, where a
|
||||
// test can reach them.
|
||||
if board.picker_key(key, screen) {
|
||||
continue;
|
||||
}
|
||||
|
||||
match key.code {
|
||||
// One arm, because the two keys mean one thing: close what is open, and
|
||||
// quit when there is nothing left to close. Two arms carrying one rule
|
||||
// is how a later edit changes it for one key and not the other, which is
|
||||
// what `q` quitting out from under an open ticket already was. The rule
|
||||
// itself is `Board::dismiss`, where a test can reach it.
|
||||
KeyCode::Esc | KeyCode::Char('q') => board.dismiss(),
|
||||
KeyCode::Esc | KeyCode::Char('q') => board.dismiss(screen),
|
||||
// The only key that leaves the board from an open ticket, which is why
|
||||
// the footer names it there.
|
||||
KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
|
||||
@@ -211,6 +228,10 @@ fn run_tui(paths: &[std::path::PathBuf], start: &std::path::Path) -> Result<()>
|
||||
// left that a vim hand would reach for. The clipboard is handed in rather
|
||||
// than reached for inside `Board`, so the suite can drive both answers.
|
||||
KeyCode::Char('y') => board.copy_selected_id(clipboard::copy),
|
||||
// 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(),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
+1569
-78
File diff suppressed because it is too large
Load Diff
+618
-39
@@ -254,13 +254,87 @@ pub fn color_text(text: &str, color: Color) -> String {
|
||||
paint(text, color, should_use_colors())
|
||||
}
|
||||
|
||||
/// What sits at a candidate `.worklane` path.
|
||||
///
|
||||
/// The distinction the walk turns on is between nothing there and something
|
||||
/// unusable there. `exists()` follows a link, so a dangling one answered the same
|
||||
/// as an empty parent and the walk carried on upward until it met a board above
|
||||
/// the project, which then became the board every write went to. Silently. With
|
||||
/// the boards kept outside the project a dangling link is an ordinary state
|
||||
/// rather than a corrupted tree: it is what you have before the boards repo is
|
||||
/// cloned, and after a board directory is renamed.
|
||||
#[derive(Debug, PartialEq)]
|
||||
enum Candidate {
|
||||
/// Nothing at that path, which is the one answer the walk carries on from.
|
||||
Absent,
|
||||
/// A directory, or a link that resolves to one.
|
||||
Board,
|
||||
/// A link that resolves to nothing, carrying the target it names.
|
||||
Dangling(std::path::PathBuf),
|
||||
/// There, and not a directory: a regular file, or a link to one.
|
||||
NotADirectory,
|
||||
}
|
||||
|
||||
/// Which of the four a `.worklane` path is.
|
||||
///
|
||||
/// `symlink_metadata` first, so the answer is about the entry itself and absence
|
||||
/// cannot be confused with a target that is gone. Only then is the link followed,
|
||||
/// which is what makes a resolvable one indistinguishable from a real directory.
|
||||
fn classify(path: &Path) -> Result<Candidate> {
|
||||
let entry = match fs::symlink_metadata(path) {
|
||||
Ok(entry) => entry,
|
||||
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Candidate::Absent),
|
||||
// Anything other than absence is a filesystem that could not answer, and
|
||||
// reading that as absence is how the walk-past worked in the first place.
|
||||
Err(error) => return Err(anyhow!("Could not read {}: {error}", path.display())),
|
||||
};
|
||||
|
||||
if !entry.is_symlink() {
|
||||
return Ok(match entry.is_dir() {
|
||||
true => Candidate::Board,
|
||||
false => Candidate::NotADirectory,
|
||||
});
|
||||
}
|
||||
|
||||
// Read whether or not it resolves: the target is the only part of the failure
|
||||
// that says what to go and fix.
|
||||
let target = fs::read_link(path).unwrap_or_else(|_| path.to_path_buf());
|
||||
|
||||
Ok(match fs::metadata(path) {
|
||||
Ok(resolved) if resolved.is_dir() => Candidate::Board,
|
||||
Ok(_) => Candidate::NotADirectory,
|
||||
Err(_) => Candidate::Dangling(target),
|
||||
})
|
||||
}
|
||||
|
||||
/// The first `.worklane` at or above `start`.
|
||||
///
|
||||
/// The symlink stays unresolved in what is returned, so a board reached through a
|
||||
/// link is the same path to everything downstream as one sitting in the project.
|
||||
pub fn find_worklane_dir(start: &Path) -> Result<std::path::PathBuf> {
|
||||
let mut current = start.canonicalize()?;
|
||||
|
||||
loop {
|
||||
let worklane_dir = current.join(".worklane");
|
||||
if worklane_dir.exists() {
|
||||
return Ok(worklane_dir);
|
||||
match classify(&worklane_dir)? {
|
||||
Candidate::Board => return Ok(worklane_dir),
|
||||
// The only answer that hands the search upward. A `.worklane` that is
|
||||
// there but unusable is this project's board and is reported here,
|
||||
// rather than quietly becoming a write to whatever sits above it.
|
||||
Candidate::Absent => {}
|
||||
Candidate::Dangling(target) => {
|
||||
return Err(anyhow!(
|
||||
"{} is a symlink to {}, which does not exist. The boards repo may not be cloned on this machine.",
|
||||
worklane_dir.display(),
|
||||
target.display()
|
||||
));
|
||||
}
|
||||
Candidate::NotADirectory => {
|
||||
return Err(anyhow!(
|
||||
"{} is not a directory. A board is a directory of ticket files.",
|
||||
worklane_dir.display()
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
if !current.pop() {
|
||||
@@ -389,14 +463,22 @@ fn status_paths(worklane_dir: &Path) -> Vec<(String, std::path::PathBuf)> {
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// The three-tier search, run over `dirs`, returning the first tier that matched
|
||||
/// The four-tier search, run over `dirs`, returning the first tier that matched
|
||||
/// anything.
|
||||
///
|
||||
/// Three tiers, filled in one pass and consulted in order. A uuid prefix has to win
|
||||
/// Four tiers, filled in one pass and consulted in order. A uuid prefix has to win
|
||||
/// outright rather than join a flat list: ticket titles reference other tickets by id,
|
||||
/// so an exact prefix match was reported as ambiguous against whichever title happened
|
||||
/// to mention it.
|
||||
///
|
||||
/// **An exact codename wins over all three.** It is the one tier that is an exact match on
|
||||
/// a field written for the purpose, so it cannot be a coincidence the way a substring can,
|
||||
/// and a codename of `v1` is too short to be tried as an id at all. Only campaigns carry
|
||||
/// the field, so for a ticket the tier is always empty and resolution is exactly what it
|
||||
/// was. It lives here rather than in a campaign-only path for the reason the rest of this
|
||||
/// function is shared: that would be a second copy of the precedence rules and a second
|
||||
/// ambiguity message.
|
||||
///
|
||||
/// Shared by tickets and campaigns rather than written twice. 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. Each entry pairs the name a match is reported
|
||||
@@ -405,6 +487,7 @@ pub fn resolve_in(search: &str, dirs: &[(String, std::path::PathBuf)]) -> Result
|
||||
let search_lower = search.to_lowercase();
|
||||
let long_enough_for_an_id = search.chars().count() >= MIN_ID_SEARCH;
|
||||
|
||||
let mut by_codename: Vec<Found> = Vec::new();
|
||||
let mut by_id: Vec<Found> = Vec::new();
|
||||
let mut by_title: Vec<Found> = Vec::new();
|
||||
let mut by_filename: Vec<Found> = Vec::new();
|
||||
@@ -429,12 +512,17 @@ pub fn resolve_in(search: &str, dirs: &[(String, std::path::PathBuf)]) -> Result
|
||||
.unwrap_or_default();
|
||||
let uuid = filename.split('_').next().unwrap_or("");
|
||||
|
||||
// Case insensitive like the other three: a codename typed back off a listing
|
||||
// has to resolve whatever case it was read in, which is the bargain the id
|
||||
// tier already takes.
|
||||
let is_codename = parse_codename(&content)
|
||||
.is_some_and(|codename| codename.to_lowercase() == search_lower);
|
||||
let by_prefix = long_enough_for_an_id && uuid.to_lowercase().starts_with(&search_lower);
|
||||
let in_title = title.to_lowercase().contains(&search_lower);
|
||||
// Still reaches the middle of a uuid, which the prefix tier cannot.
|
||||
let in_filename = filename.to_lowercase().contains(&search_lower);
|
||||
|
||||
if !(by_prefix || in_title || in_filename) {
|
||||
if !(is_codename || by_prefix || in_title || in_filename) {
|
||||
continue;
|
||||
}
|
||||
|
||||
@@ -444,7 +532,9 @@ pub fn resolve_in(search: &str, dirs: &[(String, std::path::PathBuf)]) -> Result
|
||||
content,
|
||||
uuid: uuid.to_string(),
|
||||
};
|
||||
if by_prefix {
|
||||
if is_codename {
|
||||
by_codename.push(found);
|
||||
} else if by_prefix {
|
||||
by_id.push(found);
|
||||
} else if in_title {
|
||||
by_title.push(found);
|
||||
@@ -454,10 +544,11 @@ pub fn resolve_in(search: &str, dirs: &[(String, std::path::PathBuf)]) -> Result
|
||||
}
|
||||
}
|
||||
|
||||
Ok(match (by_id.is_empty(), by_title.is_empty()) {
|
||||
(false, _) => by_id,
|
||||
(true, false) => by_title,
|
||||
(true, true) => by_filename,
|
||||
Ok(match (by_codename.is_empty(), by_id.is_empty(), by_title.is_empty()) {
|
||||
(false, _, _) => by_codename,
|
||||
(true, false, _) => by_id,
|
||||
(true, true, false) => by_title,
|
||||
(true, true, true) => by_filename,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -846,6 +937,13 @@ fn metadata_value_cell(name: &str, value: &str, colored: bool, campaign: &str) -
|
||||
return paint(value, Color::Grey, colored);
|
||||
}
|
||||
|
||||
// The same word in the same colour as the label a card draws, since `tag_color` is a
|
||||
// pure function of it. No mark here: the field name has already said what this is,
|
||||
// and the mark is what tells a campaign from a tag on a row that holds both.
|
||||
if name == CODENAME_FIELD {
|
||||
return paint(value, tag_color(value), colored);
|
||||
}
|
||||
|
||||
if name == "Tags" {
|
||||
return paint_tags(value, colored);
|
||||
}
|
||||
@@ -1133,6 +1231,66 @@ pub fn set_metadata_field(content: &str, field: &str, value: &str, title: &str)
|
||||
/// board.
|
||||
pub const CAMPAIGN_FIELD: &str = "Campaign";
|
||||
|
||||
/// The metadata field naming a campaign in a word, beside the uuid that addresses it.
|
||||
///
|
||||
/// A campaign is filed for a release or a migration, and those have names people already
|
||||
/// use: `v1`, `beaver`. The uuid is what everything stores and the title is a sentence, so
|
||||
/// neither is what a card has room to print. This is the short form, written by
|
||||
/// `campaign add --codename` and nothing else.
|
||||
///
|
||||
/// Optional, and a campaign without one is not a lesser campaign: every campaign filed
|
||||
/// before this existed has no field at all, which reads as unset the way an absent
|
||||
/// Campaign field does.
|
||||
pub const CODENAME_FIELD: &str = "Codename";
|
||||
|
||||
/// The mark a campaign carries where it is drawn as a label.
|
||||
///
|
||||
/// Not `#`, which is the tag marker: the two sit on the same row of a card and the row
|
||||
/// would read as one list of tags with a stranger in it. A tilde is ASCII, so it renders
|
||||
/// wherever `#` does, and it is not `@`, which reads as a person on every board anyone
|
||||
/// has used.
|
||||
///
|
||||
/// One glyph, so the campaign on a card and the campaign in the picker are the same
|
||||
/// thing said the same way.
|
||||
pub const CAMPAIGN_MARK: &str = "~";
|
||||
|
||||
/// The campaign codename a file names, or nothing when it names none.
|
||||
///
|
||||
/// Absent, unset and empty are one answer, the bargain [`parse_campaign`] and
|
||||
/// [`parse_tags`] both take: a campaign filed before the field existed carries no line at
|
||||
/// all, and one whose line reads `_Not set_` has no codename either.
|
||||
pub fn parse_codename(content: &str) -> Option<String> {
|
||||
let value = parse_ticket_field(content, CODENAME_FIELD);
|
||||
|
||||
match is_unknown_value(&value) || value.trim().is_empty() {
|
||||
true => None,
|
||||
false => Some(value.trim().to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
/// A campaign as a label: the mark, then the codename, or the short id when it has none.
|
||||
///
|
||||
/// The id is the fallback rather than the title, which is a sentence and would not fit the
|
||||
/// row this is drawn on. It says little, which is the whole reason the codename field
|
||||
/// exists, but it is addressable: `campaign show` takes it.
|
||||
///
|
||||
/// **A codename takes its own colour from [`tag_color`] and the fallback takes grey.** The
|
||||
/// colour is what groups a campaign across the cards that carry it, and one word is one
|
||||
/// colour in every view for the same reason a tag is. Grey on the id, rather than the red
|
||||
/// a uuid is drawn in everywhere else, keeps a reserved meaning off a `TAG_COLORS` slot in
|
||||
/// the one case where the label is an id: grey already means what a reader skips, which is
|
||||
/// what a campaign with no codename has to say for itself.
|
||||
///
|
||||
/// A `Cell`, not a string, so the CLI paints it and the board makes a span of it, the way
|
||||
/// a relation row already works. The bold is the board's: it is there to win a row against
|
||||
/// the tags, and nothing in the CLI shares a line with them.
|
||||
pub fn campaign_label(uuid: &str, codename: Option<&str>) -> Cell {
|
||||
match codename {
|
||||
Some(codename) => Cell::colored(format!("{CAMPAIGN_MARK}{codename}"), tag_color(codename)),
|
||||
None => Cell::colored(format!("{CAMPAIGN_MARK}{}", short_id(uuid)), Color::Grey),
|
||||
}
|
||||
}
|
||||
|
||||
/// The campaign uuid a ticket names, or nothing when it names none.
|
||||
///
|
||||
/// Absent and unset are the same answer: a ticket that has never been assigned has no
|
||||
@@ -1177,8 +1335,16 @@ pub fn parse_tags(content: &str) -> Vec<String> {
|
||||
/// stamps follow `Created At`, since they answer the same question it does about a
|
||||
/// later moment, and they are in flow order for a reader who sees one after another
|
||||
/// across a board.
|
||||
const METADATA_ORDER: [&str; 11] = [
|
||||
///
|
||||
/// `Codename` is a *campaign's* field and sits here for the same reason Campaign does: this
|
||||
/// is the one list that decides where an inserted field lands, and a campaign filed before
|
||||
/// the field existed is precisely the file `campaign set --codename` has to insert into.
|
||||
/// Directly after ID, because that is where `campaign_body` writes it, so a campaign given
|
||||
/// a codename later ends up with the same file as one filed with it. Nothing ever upserts
|
||||
/// it on a ticket, so its place in a ticket's order costs nothing.
|
||||
const METADATA_ORDER: [&str; 12] = [
|
||||
"ID",
|
||||
CODENAME_FIELD,
|
||||
"Priority",
|
||||
"Tags",
|
||||
"Due",
|
||||
@@ -1272,28 +1438,38 @@ pub const COMMITTED_ON_FIELD: &str = "Committed On";
|
||||
pub const SUBMITTED_ON_FIELD: &str = "Submitted On";
|
||||
pub const COMPLETED_ON_FIELD: &str = "Completed On";
|
||||
|
||||
/// Stamp the field of the status being entered and drop the other two.
|
||||
/// Stamp the field of the status being entered and drop the ones after it.
|
||||
///
|
||||
/// A stamp is present exactly while the ticket sits in its status, so the three are
|
||||
/// mutually exclusive: entering writes one, leaving removes it, and re-entering
|
||||
/// restamps rather than keeping the first value. That is what keeps a ticket moved
|
||||
/// backward under `-f` from carrying a `Completed On` for work it has undone, and it is
|
||||
/// the line between these fields and d4ce964's history log. Metadata carries current
|
||||
/// state, which is why `Status` is a field at all; the trail of how the ticket got here
|
||||
/// belongs to the log, and a stamp left behind would be a second copy of that job.
|
||||
/// The stamps accumulate down the flow rather than being mutually exclusive, so a
|
||||
/// ticket that has walked the whole way carries `Created At`, `Committed On`,
|
||||
/// `Submitted On` and `Completed On` side by side and the journey behind it is legible.
|
||||
/// Presence therefore means the ticket got that far and has not been sent back past it,
|
||||
/// not that it is sitting there now; `Status` is what says where it is.
|
||||
///
|
||||
/// One arrival rule covers both directions. A backward move truncates the journey at
|
||||
/// the target, so `done` back to `reviewing` drops `Completed On` and keeps the two
|
||||
/// before it, and anything back to `backlog` drops all three. A forward skip under `-f`
|
||||
/// has nothing after it to clear, so `backlog` straight to `done` stamps `Completed On`
|
||||
/// alone and leaves the stages it jumped over unwritten rather than fabricated.
|
||||
/// Re-entering restamps rather than keeping the earlier value.
|
||||
///
|
||||
/// This is still not d4ce964's history log. These fields answer how far and when, once
|
||||
/// per stage; every status change, every owner and every tag along the way is the log's
|
||||
/// job and must not be grown here. `backlog` has no stamp, `Created At` answers for it.
|
||||
///
|
||||
/// The time comes in as a string rather than being read here, so the caller stamps the
|
||||
/// same moment it reports and a test can pin the value.
|
||||
pub fn set_status_stamp(content: &str, target: Status, now: &str, title: &str) -> Result<String> {
|
||||
let mut content = content.to_string();
|
||||
|
||||
// Every status but the target, so a skipping move under `-f` clears the stamps of
|
||||
// the stages it jumped over as well as the one it left.
|
||||
for status in Status::ALL {
|
||||
if status == target {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Every status after the target, off the flow order `Status::ALL` already holds
|
||||
// rather than a case per move, so arrival alone decides what is cleared and a
|
||||
// backward move and a skip are the same rule.
|
||||
for status in Status::ALL
|
||||
.iter()
|
||||
.skip_while(|status| **status != target)
|
||||
.skip(1)
|
||||
{
|
||||
let Some(field) = status.stamp_field() else {
|
||||
continue;
|
||||
};
|
||||
@@ -1574,6 +1750,25 @@ fn section_body(lines: &[&str], heading: &str) -> Option<std::ops::Range<usize>>
|
||||
Some(after..section_end(lines, after))
|
||||
}
|
||||
|
||||
/// The first line of a section's body, or nothing when the section is absent or holds
|
||||
/// only its placeholder.
|
||||
///
|
||||
/// For a view with one row to spend on prose: the board's campaign frame and its picker
|
||||
/// both want the opening line of a description and have no room for the rest. Through
|
||||
/// [`section_body`] rather than a scan of its own, so what counts as the section is
|
||||
/// decided in one place, and the placeholder reads as nothing here the way it does to
|
||||
/// `append`.
|
||||
pub fn section_opening(content: &str, section: &Section) -> Option<String> {
|
||||
let lines: Vec<&str> = content.lines().collect();
|
||||
let body = section_body(&lines, section.heading)?;
|
||||
|
||||
lines[body]
|
||||
.iter()
|
||||
.map(|line| line.trim())
|
||||
.find(|line| !line.is_empty() && *line != section.placeholder)
|
||||
.map(|line| line.to_string())
|
||||
}
|
||||
|
||||
/// Where the body's content ends, ignoring the blank lines that separate it from
|
||||
/// whatever follows.
|
||||
fn body_content_end(lines: &[&str], body: &std::ops::Range<usize>) -> usize {
|
||||
@@ -2385,8 +2580,8 @@ pub enum Status {
|
||||
}
|
||||
|
||||
impl Status {
|
||||
/// Every status, in flow order. The one list, which [`status_dirs`] and `mv` both
|
||||
/// read rather than spelling the four names again.
|
||||
/// Every status, in flow order. The one list, which [`status_dirs`], `mv` and every
|
||||
/// caller of [`by_status_order`] read rather than spelling the four names again.
|
||||
pub const ALL: [Status; 4] = [
|
||||
Status::Backlog,
|
||||
Status::Committed,
|
||||
@@ -2542,6 +2737,48 @@ pub struct TicketItem {
|
||||
/// The file this came from. The listing ignores it; the TUI opens it for the
|
||||
/// detail view rather than resolving the ticket a second time.
|
||||
pub path: std::path::PathBuf,
|
||||
/// The time `mv` stamped on entering committed, or `None` for a ticket that has
|
||||
/// never got that far.
|
||||
///
|
||||
/// Read here for the reason `criteria` is, and it is what its column is ordered by:
|
||||
/// a comparator that read the file would re-read every ticket on every comparison,
|
||||
/// where this pass reads each one once.
|
||||
pub committed_on: Option<String>,
|
||||
/// The same for reviewing.
|
||||
pub submitted_on: Option<String>,
|
||||
/// The same for done.
|
||||
pub completed_on: Option<String>,
|
||||
}
|
||||
|
||||
impl TicketItem {
|
||||
/// The stamp the ticket entered a status with, which is what that column sorts on.
|
||||
///
|
||||
/// A slot per status rather than a lookup by field name, so a fifth status carrying
|
||||
/// a stamp is a compile error here the way it is in [`Status::stamp_field`].
|
||||
/// Backlog has none: nothing stamps it, and `Created At` is not an entry time, so
|
||||
/// every ticket in that column answers `None` and the whole order is the fallback.
|
||||
fn entry_stamp(&self, status: Status) -> Option<&str> {
|
||||
match status {
|
||||
Status::Backlog => None,
|
||||
Status::Committed => self.committed_on.as_deref(),
|
||||
Status::Reviewing => self.submitted_on.as_deref(),
|
||||
Status::Done => self.completed_on.as_deref(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The stamp a ticket carries for a status, or `None` for one it has not reached.
|
||||
///
|
||||
/// The field name comes off [`Status::stamp_field`], so what is read here cannot drift
|
||||
/// from what `mv` writes. An absent field reads as `_Not set_` like every other, and a
|
||||
/// stamp is machine-written so that spelling never appears as a value; both count as no
|
||||
/// stamp rather than as a time.
|
||||
fn parse_stamp(content: &str, status: Status) -> Option<String> {
|
||||
let value = parse_ticket_field(content, status.stamp_field()?);
|
||||
match is_unknown_value(&value) {
|
||||
true => None,
|
||||
false => Some(value),
|
||||
}
|
||||
}
|
||||
|
||||
/// The date part of a due value, for a view with only a corner to spend on it.
|
||||
@@ -2703,6 +2940,9 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
uuid: parse_ticket_field(&content, "ID"),
|
||||
blockers,
|
||||
path: e.path(),
|
||||
committed_on: parse_stamp(&content, Status::Committed),
|
||||
submitted_on: parse_stamp(&content, Status::Reviewing),
|
||||
completed_on: parse_stamp(&content, Status::Done),
|
||||
})
|
||||
})
|
||||
.collect();
|
||||
@@ -2711,11 +2951,13 @@ pub fn collect_ticket_items(status_path: impl AsRef<Path>) -> Result<Vec<TicketI
|
||||
Ok(items)
|
||||
}
|
||||
|
||||
/// The order a status column is read in: priority first, title as the tiebreak.
|
||||
/// The order the backlog is read in, and the tiebreak every other column falls back to:
|
||||
/// priority first, title second.
|
||||
///
|
||||
/// Named and exported because the board's All tab merges several boards' columns into
|
||||
/// one and has to land in the order the listing uses. A merge sorted a second way
|
||||
/// would put a p1 below a p5 depending on which project it came from.
|
||||
/// one and has to land in one order. A merge sorted a second way would put a p1 below a
|
||||
/// p5 depending on which project it came from, and the merge spans statuses, so no
|
||||
/// single stamp governs it.
|
||||
pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
|
||||
a.priority
|
||||
.rank()
|
||||
@@ -2723,6 +2965,39 @@ pub fn by_priority_then_title(a: &TicketItem, b: &TicketItem) -> std::cmp::Order
|
||||
.then_with(|| a.title.to_lowercase().cmp(&b.title.to_lowercase()))
|
||||
}
|
||||
|
||||
/// The order one status column is read in, keyed on the status.
|
||||
///
|
||||
/// Priority is the clock in the backlog, and that column keeps exactly the order it has
|
||||
/// always printed. Past the backlog the question changes: committed asks what has waited
|
||||
/// longest, reviewing what was handed over first, done what just landed. The head of
|
||||
/// every column is therefore what the reader acts on next, which is ascending by entry
|
||||
/// stamp in committed and reviewing and descending in done, the way a changelog reads.
|
||||
///
|
||||
/// A ticket with no stamp sinks below every stamped one in its column. A missing time is
|
||||
/// unknown, not ancient, and unknown must not claim the head of a queue ahead of a wait
|
||||
/// somebody can point at. Reading absence as the epoch would come free from the string
|
||||
/// comparison and put every legacy ticket first on data nothing verified.
|
||||
///
|
||||
/// The comparison is a string comparison. The stamp format is `%Y-%m-%d %H:%M:%S`, where
|
||||
/// lexicographic order is chronological order, the same property `Due` already relies
|
||||
/// on, so there is no date parsing at sort time. Equal stamps happen, `mv` writes whole
|
||||
/// seconds, and they fall through to priority and title like everything else.
|
||||
pub fn by_status_order(status: Status, a: &TicketItem, b: &TicketItem) -> std::cmp::Ordering {
|
||||
let by_stamp = match (a.entry_stamp(status), b.entry_stamp(status)) {
|
||||
(Some(left), Some(right)) => match status {
|
||||
Status::Done => right.cmp(left),
|
||||
_ => left.cmp(right),
|
||||
},
|
||||
(Some(_), None) => std::cmp::Ordering::Less,
|
||||
(None, Some(_)) => std::cmp::Ordering::Greater,
|
||||
// Both unstamped, which is every ticket in the backlog: the fallback is the
|
||||
// whole order there rather than a tiebreak.
|
||||
(None, None) => std::cmp::Ordering::Equal,
|
||||
};
|
||||
|
||||
by_stamp.then_with(|| by_priority_then_title(a, b))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -3292,10 +3567,10 @@ mod tests {
|
||||
assert!(error.to_string().contains("Campaign"), "{error}");
|
||||
}
|
||||
|
||||
/// The one stamp the target status carries, and nothing of the others: the fields
|
||||
/// are current state, not a record of every stage the ticket has been through.
|
||||
/// The stamp of the status being entered, added to what the ticket already carries:
|
||||
/// the fields accumulate down the flow, so the stages behind it stay readable.
|
||||
#[test]
|
||||
fn entering_a_status_stamps_its_field_and_clears_the_rest() {
|
||||
fn entering_a_status_stamps_its_field_and_keeps_the_ones_before_it() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n- **Committed On**: 2026-08-01 09:00:00\n- **Status**: committed\n",
|
||||
);
|
||||
@@ -3304,25 +3579,64 @@ mod tests {
|
||||
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(!updated.contains("**Committed On**"), "{updated}");
|
||||
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own, so a backward move under `-f` leaves the ticket
|
||||
/// carrying none rather than a Completed On for work it has undone.
|
||||
/// Arrival truncates the journey at the target, so the stage the ticket has been
|
||||
/// sent back out of is dropped and the ones it still got through are not.
|
||||
#[test]
|
||||
fn arriving_removes_the_stamps_of_the_statuses_after_the_target() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
);
|
||||
|
||||
let updated =
|
||||
set_status_stamp(&content, Status::Reviewing, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(!updated.contains("**Completed On**"), "{updated}");
|
||||
assert!(updated.contains("- **Committed On**: 2026-08-01 09:00:00"), "{updated}");
|
||||
assert!(updated.contains("- **Submitted On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own and every status follows it, so a ticket forced
|
||||
/// all the way back carries none of the three rather than a trail it has undone.
|
||||
#[test]
|
||||
fn moving_back_to_backlog_leaves_no_stamp_behind() {
|
||||
let content = with_metadata(
|
||||
"- **ID**: abc\n- **Completed On**: 2026-08-01 09:00:00\n- **Status**: done\n",
|
||||
"- **ID**: abc\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
);
|
||||
|
||||
let updated =
|
||||
set_status_stamp(&content, Status::Backlog, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(!updated.contains("**Completed On**"), "{updated}");
|
||||
for field in [COMMITTED_ON_FIELD, SUBMITTED_ON_FIELD, COMPLETED_ON_FIELD] {
|
||||
assert!(!updated.contains(&format!("**{}**", field)), "{updated}");
|
||||
}
|
||||
assert!(!updated.contains("2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(updated.contains("- **ID**: abc\n- **Status**: done\n"), "{updated}");
|
||||
}
|
||||
|
||||
/// A skip stamps the target and nothing else. The stages it jumped over are left
|
||||
/// unwritten rather than given a time the ticket never spent there.
|
||||
#[test]
|
||||
fn a_forward_skip_stamps_only_the_status_it_lands_in() {
|
||||
let content = with_metadata("- **ID**: abc\n- **Status**: backlog\n");
|
||||
|
||||
let updated = set_status_stamp(&content, Status::Done, "2026-08-22 10:11:12", "T").unwrap();
|
||||
|
||||
assert!(updated.contains("- **Completed On**: 2026-08-22 10:11:12"), "{updated}");
|
||||
assert!(!updated.contains("**Committed On**"), "{updated}");
|
||||
assert!(!updated.contains("**Submitted On**"), "{updated}");
|
||||
}
|
||||
|
||||
/// Re-entry is the time of the move that brought it back, not the first one.
|
||||
#[test]
|
||||
fn re_entering_a_status_restamps_rather_than_keeping_the_earlier_value() {
|
||||
@@ -3361,6 +3675,170 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
/// A listed ticket with only the fields the column order reads: its title, its
|
||||
/// priority and the stamp for the status being sorted.
|
||||
fn listed(title: &str, level: u8, status: Status, stamp: Option<&str>) -> TicketItem {
|
||||
let stamp = stamp.map(|value| value.to_string());
|
||||
|
||||
TicketItem {
|
||||
title: title.to_string(),
|
||||
owner: NOT_SET.to_string(),
|
||||
due: NOT_SET.to_string(),
|
||||
id: "0000000".to_string(),
|
||||
created: String::new(),
|
||||
priority: Priority::Level(level),
|
||||
criteria: None,
|
||||
campaign: None,
|
||||
tags: Vec::new(),
|
||||
uuid: NOT_SET.to_string(),
|
||||
blockers: Vec::new(),
|
||||
path: std::path::PathBuf::new(),
|
||||
committed_on: match status {
|
||||
Status::Committed => stamp.clone(),
|
||||
_ => None,
|
||||
},
|
||||
submitted_on: match status {
|
||||
Status::Reviewing => stamp.clone(),
|
||||
_ => None,
|
||||
},
|
||||
completed_on: match status {
|
||||
Status::Done => stamp,
|
||||
_ => None,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
/// Sorted the way the column is read, titles out, so a case reads as the order it
|
||||
/// asserts rather than as a pair of comparisons.
|
||||
fn ordered(status: Status, mut items: Vec<TicketItem>) -> Vec<String> {
|
||||
items.sort_by(|a, b| by_status_order(status, a, b));
|
||||
items.into_iter().map(|item| item.title).collect()
|
||||
}
|
||||
|
||||
/// The backlog is the one column priority still governs, and it prints exactly what
|
||||
/// it always has: the stamps a ticket carries from an earlier trip through the flow
|
||||
/// do not reach it, because backlog has no stamp of its own to sort on.
|
||||
#[test]
|
||||
fn the_backlog_keeps_priority_then_title() {
|
||||
let items = vec![
|
||||
listed("zebra", 5, Status::Backlog, None),
|
||||
listed("alpha", 1, Status::Backlog, None),
|
||||
listed("beta", 1, Status::Backlog, None),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Backlog, items), ["alpha", "beta", "zebra"]);
|
||||
}
|
||||
|
||||
/// Committed and reviewing are queues: the head is what has waited longest, which is
|
||||
/// where the reader picks next from.
|
||||
#[test]
|
||||
fn committed_and_reviewing_list_the_oldest_stamp_first() {
|
||||
for status in [Status::Committed, Status::Reviewing] {
|
||||
let items = vec![
|
||||
listed("newest", 1, status, Some("2026-08-03 09:00:00")),
|
||||
listed("oldest", 5, status, Some("2026-08-01 09:00:00")),
|
||||
listed("middle", 1, status, Some("2026-08-02 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(status, items), ["oldest", "middle", "newest"], "{status:?}");
|
||||
}
|
||||
}
|
||||
|
||||
/// Done reads like a changelog: what just landed is at the top, and priority no
|
||||
/// longer decides anything about finished work.
|
||||
#[test]
|
||||
fn done_lists_the_newest_stamp_first() {
|
||||
let items = vec![
|
||||
listed("first", 1, Status::Done, Some("2026-08-01 09:00:00")),
|
||||
listed("last", 5, Status::Done, Some("2026-08-03 09:00:00")),
|
||||
listed("middle", 1, Status::Done, Some("2026-08-02 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Done, items), ["last", "middle", "first"]);
|
||||
}
|
||||
|
||||
/// A missing stamp is unknown, not ancient. Reading absence as the epoch would come
|
||||
/// free from the string comparison and hand the head of the queue to every legacy
|
||||
/// ticket, so it sinks instead, in both directions.
|
||||
#[test]
|
||||
fn a_ticket_with_no_stamp_sorts_below_every_stamped_one() {
|
||||
for status in [Status::Committed, Status::Reviewing, Status::Done] {
|
||||
let items = vec![
|
||||
listed("unstamped", 1, status, None),
|
||||
listed("stamped", 5, status, Some("2026-08-01 09:00:00")),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(status, items), ["stamped", "unstamped"], "{status:?}");
|
||||
}
|
||||
}
|
||||
|
||||
/// `mv` writes whole seconds, so two moves in the same second is a real tie rather
|
||||
/// than a hypothetical one, and it falls through to the order the backlog uses.
|
||||
#[test]
|
||||
fn equal_stamps_fall_back_to_priority_then_title() {
|
||||
let same = Some("2026-08-01 09:00:00");
|
||||
let items = vec![
|
||||
listed("zebra", 1, Status::Committed, same),
|
||||
listed("beta", 3, Status::Committed, same),
|
||||
listed("alpha", 3, Status::Committed, same),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Committed, items), ["zebra", "alpha", "beta"]);
|
||||
}
|
||||
|
||||
/// Two unstamped tickets in one column are ordered among themselves the way the
|
||||
/// backlog is, rather than left in whatever order the directory handed them back.
|
||||
#[test]
|
||||
fn unstamped_tickets_are_ordered_among_themselves_by_priority_then_title() {
|
||||
let items = vec![
|
||||
listed("zebra", 1, Status::Done, None),
|
||||
listed("beta", 3, Status::Done, None),
|
||||
listed("alpha", 3, Status::Done, None),
|
||||
];
|
||||
|
||||
assert_eq!(ordered(Status::Done, items), ["zebra", "alpha", "beta"]);
|
||||
}
|
||||
|
||||
/// The stamps come off the pass that builds the listing, not off a second read at
|
||||
/// comparison time, which is what makes an ordered column cost one read per file.
|
||||
#[test]
|
||||
fn collect_ticket_items_reads_the_stamps_the_order_sorts_on() {
|
||||
let dir = std::env::temp_dir().join(format!("worklane-stamps-{}", uuid::Uuid::new_v4()));
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
|
||||
fs::write(
|
||||
dir.join("aaaa_walked.md"),
|
||||
"# Walked\n\n## Metadata\n\n\
|
||||
- **ID**: aaaa\n\
|
||||
- **Committed On**: 2026-08-01 09:00:00\n\
|
||||
- **Submitted On**: 2026-08-02 09:00:00\n\
|
||||
- **Completed On**: 2026-08-03 09:00:00\n\
|
||||
- **Status**: done\n",
|
||||
)
|
||||
.unwrap();
|
||||
fs::write(
|
||||
dir.join("bbbb_fresh.md"),
|
||||
"# Fresh\n\n## Metadata\n\n- **ID**: bbbb\n- **Status**: backlog\n",
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let items = collect_ticket_items(&dir).unwrap();
|
||||
|
||||
let walked = items.iter().find(|item| item.title == "Walked").unwrap();
|
||||
assert_eq!(walked.committed_on.as_deref(), Some("2026-08-01 09:00:00"));
|
||||
assert_eq!(walked.submitted_on.as_deref(), Some("2026-08-02 09:00:00"));
|
||||
assert_eq!(walked.completed_on.as_deref(), Some("2026-08-03 09:00:00"));
|
||||
|
||||
// Absent reads as no stamp rather than as the `_Not set_` every other field
|
||||
// falls back to, so the order sinks it instead of comparing that text.
|
||||
let fresh = items.iter().find(|item| item.title == "Fresh").unwrap();
|
||||
assert_eq!(fresh.committed_on, None);
|
||||
assert_eq!(fresh.submitted_on, None);
|
||||
assert_eq!(fresh.completed_on, None);
|
||||
|
||||
fs::remove_dir_all(&dir).unwrap();
|
||||
}
|
||||
|
||||
/// Removal is scoped to the section for the same reason the write is: a description
|
||||
/// quoting a field marker is prose, and rewriting it would corrupt the ticket text
|
||||
/// while leaving the real field in place.
|
||||
@@ -4373,4 +4851,105 @@ mod tests {
|
||||
"{rendered:?}"
|
||||
);
|
||||
}
|
||||
|
||||
// ----------------------------------------------------- finding the board --
|
||||
|
||||
/// A project directory under a temp root.
|
||||
///
|
||||
/// The root is canonicalized because `find_worklane_dir` canonicalizes its
|
||||
/// start: on a system whose temp path runs through a link, the two spellings
|
||||
/// of the same directory would not compare equal.
|
||||
fn project_in(root: &tempfile::TempDir) -> std::path::PathBuf {
|
||||
let dir = root.path().canonicalize().unwrap().join("project");
|
||||
fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
|
||||
/// The failure names the target, since the link is not the thing to fix, and it
|
||||
/// does not say to run `init`: that answer belongs to an empty tree, and giving
|
||||
/// it here points at the wrong problem.
|
||||
#[test]
|
||||
fn a_dangling_board_link_is_reported_with_its_target() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let target = project.parent().unwrap().join("boards/2fed877-the-board");
|
||||
std::os::unix::fs::symlink(&target, project.join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains(&target.display().to_string()), "{error}");
|
||||
assert!(error.contains("boards repo"), "{error}");
|
||||
assert!(!error.contains("worklane init"), "{error}");
|
||||
}
|
||||
|
||||
/// The bug this was written for: `exists()` follows the link, so a dangling one
|
||||
/// answered false, the walk carried on up the tree, and the board above the
|
||||
/// project became the board every write landed in.
|
||||
#[test]
|
||||
fn a_dangling_board_link_does_not_reach_the_board_above_it() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let above = project.parent().unwrap().join(".worklane");
|
||||
fs::create_dir_all(&above).unwrap();
|
||||
let link = project.join(".worklane");
|
||||
std::os::unix::fs::symlink(project.parent().unwrap().join("gone"), &link).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains(&link.display().to_string()), "{error}");
|
||||
|
||||
// And the walk really would have reached it, so the assertion above is
|
||||
// about where the walk stopped rather than about an empty tree.
|
||||
assert_eq!(find_worklane_dir(project.parent().unwrap()).unwrap(), above);
|
||||
}
|
||||
|
||||
/// Nothing at that path is still the one answer the walk carries on from.
|
||||
#[test]
|
||||
fn no_worklane_at_all_lets_the_walk_carry_on_upward() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let above = project.parent().unwrap().join(".worklane");
|
||||
fs::create_dir_all(&above).unwrap();
|
||||
|
||||
assert_eq!(find_worklane_dir(&project).unwrap(), above);
|
||||
}
|
||||
|
||||
/// A link that resolves is the board, and what comes back is the link rather
|
||||
/// than its target: `.worklane/backlog` has to read the same either way.
|
||||
#[test]
|
||||
fn a_link_to_a_board_resolves_the_way_a_directory_does() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let board = project.parent().unwrap().join("boards/2fed877-the-board");
|
||||
fs::create_dir_all(&board).unwrap();
|
||||
let link = project.join(".worklane");
|
||||
std::os::unix::fs::symlink(&board, &link).unwrap();
|
||||
|
||||
assert_eq!(find_worklane_dir(&project).unwrap(), link);
|
||||
}
|
||||
|
||||
/// A regular file is reported rather than stepped over, and a board above it
|
||||
/// does not make it the walk's problem to solve.
|
||||
#[test]
|
||||
fn a_regular_file_where_the_board_goes_is_an_error() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
fs::write(project.join(".worklane"), "board = \"2fed877\"\n").unwrap();
|
||||
fs::create_dir_all(project.parent().unwrap().join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains("not a directory"), "{error}");
|
||||
}
|
||||
|
||||
/// A link that resolves to a file, which the follow catches and the entry check
|
||||
/// on its own cannot: the entry is a symlink and the target is not a directory.
|
||||
#[test]
|
||||
fn a_link_to_a_file_is_not_a_board_either() {
|
||||
let root = tempfile::tempdir().unwrap();
|
||||
let project = project_in(&root);
|
||||
let file = project.parent().unwrap().join("pointer.toml");
|
||||
fs::write(&file, "board = \"2fed877\"\n").unwrap();
|
||||
std::os::unix::fs::symlink(&file, project.join(".worklane")).unwrap();
|
||||
|
||||
let error = find_worklane_dir(&project).unwrap_err().to_string();
|
||||
assert!(error.contains("not a directory"), "{error}");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -597,3 +597,30 @@ fn add_names_the_ticket_and_the_path_when_the_write_fails() {
|
||||
chmod(&backlog, 0o755);
|
||||
assert_eq!(fs::read_dir(&backlog).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
/// The board above the project is real and empty, and stays empty: a dangling
|
||||
/// `.worklane` link used to read as no board here, and the walk then wrote the
|
||||
/// ticket into whatever board sat above it.
|
||||
#[test]
|
||||
fn add_writes_nothing_when_the_board_link_does_not_resolve() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let above = setup_worklane(&temp);
|
||||
|
||||
let project = temp.child("project");
|
||||
project.create_dir_all().unwrap();
|
||||
let target = temp.path().join("boards/2fed877-the-board");
|
||||
std::os::unix::fs::symlink(&target, project.path().join(".worklane")).unwrap();
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let assert = cmd
|
||||
.current_dir(project.path())
|
||||
.args(["add", "--title", "Should not land"])
|
||||
.assert()
|
||||
.failure();
|
||||
|
||||
let stderr = String::from_utf8(assert.get_output().stderr.clone()).unwrap();
|
||||
assert!(stderr.contains(&target.display().to_string()), "{stderr}");
|
||||
assert!(stderr.contains("boards repo"), "{stderr}");
|
||||
|
||||
assert_eq!(fs::read_dir(above.join("backlog")).unwrap().count(), 0);
|
||||
}
|
||||
|
||||
@@ -13,6 +13,8 @@ const CAMP_B: &str = "bb22cc33-44dd-4ee5-8ff6-001122334455";
|
||||
const MEMBER: &str = "641e3d5c-1b0e-4d2f-9a7e-3c8b5f0a2d61";
|
||||
const OTHER: &str = "b1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
|
||||
const LONER: &str = "f1f2f3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f";
|
||||
/// A second done member, for the one test that needs two in one column to see an order.
|
||||
const LATE: &str = "a9a8a7a6-5b4c-4d3e-8f2a-1b0c9d8e7f60";
|
||||
|
||||
fn setup_worklane(temp: &TempDir) -> PathBuf {
|
||||
let worklane = temp.child(".worklane");
|
||||
@@ -144,6 +146,21 @@ fn find(worklane: &Path, uuid: &str) -> PathBuf {
|
||||
panic!("no file for ticket {uuid}");
|
||||
}
|
||||
|
||||
/// A campaign's content by uuid, found rather than named, since `campaign set --title`
|
||||
/// renames the file and a test that named it would be asserting the old name.
|
||||
fn campaign_file(worklane: &Path, uuid: &str) -> String {
|
||||
for entry in fs::read_dir(worklane.join("campaigns"))
|
||||
.unwrap()
|
||||
.filter_map(|e| e.ok())
|
||||
{
|
||||
if entry.file_name().to_string_lossy().starts_with(uuid) {
|
||||
return fs::read_to_string(entry.path()).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
panic!("no file for campaign {uuid}");
|
||||
}
|
||||
|
||||
fn ticket(worklane: &Path, uuid: &str) -> String {
|
||||
fs::read_to_string(find(worklane, uuid)).unwrap()
|
||||
}
|
||||
@@ -413,6 +430,47 @@ fn campaign_ls_lists_campaigns_with_their_member_counts() {
|
||||
assert!(listing.contains("v2 release | no members"), "{listing}");
|
||||
}
|
||||
|
||||
/// The machine-readable listing, the same two fields and the same shape as `ls --ids`.
|
||||
#[test]
|
||||
fn campaign_ls_ids_prints_the_id_and_the_title_tab_separated() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let _worklane = board(&temp);
|
||||
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls", "--ids"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let listing = stdout(&out);
|
||||
assert_eq!(
|
||||
listing.lines().collect::<Vec<_>>(),
|
||||
vec![
|
||||
format!("{}\tv1 release", &CAMP_A[..7]),
|
||||
format!("{}\tv2 release", &CAMP_B[..7]),
|
||||
]
|
||||
);
|
||||
|
||||
// Nothing decorated: no heading, no member count, no escape.
|
||||
assert!(!listing.contains("Campaigns:"), "{listing}");
|
||||
assert!(!listing.contains("done"), "{listing}");
|
||||
assert!(!listing.contains('\u{1b}'), "{listing}");
|
||||
}
|
||||
|
||||
/// A completion offers nothing rather than a sentence, so the empty case that prints
|
||||
/// prose for a reader has to stay out of the parsed path.
|
||||
#[test]
|
||||
fn campaign_ls_ids_says_nothing_on_a_board_with_no_campaigns() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls", "--ids"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert_eq!(stdout(&out), "");
|
||||
|
||||
// The decorated listing still explains itself.
|
||||
assert!(stdout(&run(&temp, &["campaign", "ls"])).contains("No campaigns yet"));
|
||||
}
|
||||
|
||||
/// A campaign is done when it holds members and every one of them is done. An empty one
|
||||
/// is neither, which is why it reads `no members` rather than `0/0 done`.
|
||||
#[test]
|
||||
@@ -451,6 +509,37 @@ fn campaign_show_prints_the_body_and_the_members_grouped_by_status() {
|
||||
assert!(!shown.contains("The loner"), "{shown}");
|
||||
}
|
||||
|
||||
/// The members of a status are listed in that status's own order, not in the board-wide
|
||||
/// one: a campaign's done list answers what just landed, for the same reason the board's
|
||||
/// column does. Every fixture is a p3, so the stamp is doing all of the work.
|
||||
#[test]
|
||||
fn campaign_show_lists_each_status_in_its_own_order() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let stamp = |uuid: &str, day: &str| {
|
||||
let path = find(&worklane, uuid);
|
||||
let body = fs::read_to_string(&path).unwrap().replace(
|
||||
"- **Status**: done\n",
|
||||
&format!("- **Completed On**: 2026-08-0{day} 09:00:00\n- **Status**: done\n"),
|
||||
);
|
||||
fs::write(&path, body).unwrap();
|
||||
};
|
||||
|
||||
// A second done member, finished after the one the fixture writes.
|
||||
create_ticket(&worklane, "done", "The late member", LATE);
|
||||
stamp(OTHER, "1");
|
||||
stamp(LATE, "3");
|
||||
|
||||
run(&temp, &["assign", "v1 release", OTHER]);
|
||||
run(&temp, &["assign", "v1 release", LATE]);
|
||||
|
||||
let shown = stdout(&run(&temp, &["campaign", "show", "aa11"]));
|
||||
let at = |needle: &str| shown.find(needle).unwrap_or_else(|| panic!("{needle}: {shown}"));
|
||||
|
||||
assert!(at("The late member") < at("The other member"), "{shown}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ls_campaign_lists_only_that_campaigns_members() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -601,3 +690,576 @@ fn an_ambiguous_campaign_lists_the_candidates() {
|
||||
assert!(message.contains("v1 release"), "{message}");
|
||||
assert!(message.contains("v2 release"), "{message}");
|
||||
}
|
||||
|
||||
// ------------------------------------------------------------------ codenames --
|
||||
|
||||
/// The codename is what the board draws on every card in a campaign, since a uuid does
|
||||
/// not fit there and a title is a sentence.
|
||||
#[test]
|
||||
fn campaign_add_writes_the_codename_under_the_id() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"--codename",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let name = campaigns(&worklane).remove(0);
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
// Under the ID, because that is what it is: a second way to say which campaign this
|
||||
// is, in a word rather than in thirty-six characters.
|
||||
let id = content.find("- **ID**:").expect("no id");
|
||||
let codename = content.find("- **Codename**:").expect("no codename");
|
||||
let owner = content.find("- **Owner**:").expect("no owner");
|
||||
assert!(id < codename && codename < owner, "{content}");
|
||||
}
|
||||
|
||||
/// A campaign filed without one carries the line unset rather than not at all, the way
|
||||
/// `add` writes an unset Due on every ticket: one shape of file is one thing for the
|
||||
/// parser to be right about, and the line is there to fill in by hand.
|
||||
#[test]
|
||||
fn a_campaign_filed_without_a_codename_carries_the_field_unset() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
run(&temp, &["campaign", "add", "--title", "No codename here"]);
|
||||
|
||||
let name = campaigns(&worklane).remove(0);
|
||||
let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap();
|
||||
|
||||
assert!(content.contains("- **Codename**: _Not set_"), "{content}");
|
||||
}
|
||||
|
||||
/// One word, checked at parse time like `--due` and `--priority`, because the board draws
|
||||
/// it as a label with a mark and no quoting: `~beaver release` on that row reads as two
|
||||
/// labels and the second one is not a campaign.
|
||||
#[test]
|
||||
fn a_codename_of_more_than_one_word_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"v1 release",
|
||||
"--codename",
|
||||
"beaver release",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("single word"), "{}", stderr(&out));
|
||||
assert!(campaigns(&worklane).is_empty(), "a campaign was filed anyway");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn an_empty_codename_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "add", "--title", "v1 release", "--codename", ""]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(campaigns(&worklane).is_empty(), "a campaign was filed anyway");
|
||||
}
|
||||
|
||||
/// The listing is where the codename is read back, so it goes between the id and the
|
||||
/// title with the mark the board draws it with: one word for one campaign, spelled the
|
||||
/// same wherever it is shown.
|
||||
#[test]
|
||||
fn campaign_ls_names_the_codename_between_the_id_and_the_title() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_campaign(&worklane, "No codename here", CAMP_B);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "ls"]);
|
||||
let listing = stdout(&out);
|
||||
|
||||
assert!(listing.contains("~v1 First public release"), "{listing}");
|
||||
// And a campaign without one spends nothing on it, the way an untagged card spends no
|
||||
// row.
|
||||
assert!(listing.contains(") No codename here"), "{listing}");
|
||||
assert!(!listing.contains("~No codename"), "{listing}");
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
/// `campaign show` renders its metadata as a table, so the field is there to read without
|
||||
/// anything being written twice.
|
||||
#[test]
|
||||
fn campaign_show_renders_the_codename_in_its_metadata() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"add",
|
||||
"--title",
|
||||
"First public release",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "show", "First public"]);
|
||||
assert!(stdout(&out).contains("Codename"), "{}", stdout(&out));
|
||||
assert!(stdout(&out).contains("v1"), "{}", stdout(&out));
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
/// A codename nobody can type is half a field, so it resolves a campaign the way its
|
||||
/// uuid and its title do. Exact, and ahead of all three: it is a match on a field written
|
||||
/// for the purpose rather than a substring that could be a coincidence.
|
||||
#[test]
|
||||
fn a_campaign_resolves_by_its_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
// Same file, plus a codename, since `create_campaign` writes none.
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let content = fs::read_to_string(&path).unwrap();
|
||||
fs::write(
|
||||
&path,
|
||||
content.replace("- **Owner**:", "- **Codename**: beaver\n- **Owner**:"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
let out = run(&temp, &["assign", "beaver", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"{}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
|
||||
// And every other command that takes a campaign, since they share one resolver.
|
||||
let out = run(&temp, &["campaign", "show", "beaver"]);
|
||||
assert!(stdout(&out).contains("v1 release"), "{}", stdout(&out));
|
||||
|
||||
let out = run(&temp, &["ls", "--campaign", "beaver"]);
|
||||
assert!(stdout(&out).contains("The member"), "{}", stdout(&out));
|
||||
}
|
||||
|
||||
/// An exact codename beats a title that merely contains the search, which is the whole
|
||||
/// reason it is a tier of its own: `v2` is a substring of `v2 release` and the exact
|
||||
/// match has to win outright rather than be reported as ambiguous against it.
|
||||
#[test]
|
||||
fn an_exact_codename_beats_a_title_that_contains_the_search() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
let path = worklane
|
||||
.join("campaigns")
|
||||
.join(format!("{}_{}.md", CAMP_A, slug("v1 release")));
|
||||
let content = fs::read_to_string(&path).unwrap();
|
||||
fs::write(&path, content.replace("- **Owner**:", "- **Codename**: v2\n- **Owner**:")).unwrap();
|
||||
|
||||
let out = run(&temp, &["assign", "v2", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"the title tier won: {}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
}
|
||||
|
||||
/// A ticket carries no codename, so the tier is empty for one and ticket resolution is
|
||||
/// exactly what it was. Pinned because the tier lives in the shared resolver: this is the
|
||||
/// half of it that must not have changed.
|
||||
#[test]
|
||||
fn a_ticket_search_is_unaffected_by_the_codename_tier() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
// The uuid prefix still wins over a title that quotes it, which is the precedence the
|
||||
// three tiers were written for.
|
||||
let out = run(&temp, &["show", "641e3d5"]);
|
||||
assert!(stdout(&out).contains("The member"), "{}", stdout(&out));
|
||||
let _ = worklane;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------- campaign set --
|
||||
|
||||
/// The point of the command: a campaign already on the board can be given a codename,
|
||||
/// which `campaign add --codename` cannot do because `add` files a new one.
|
||||
#[test]
|
||||
fn campaign_set_gives_a_filed_campaign_a_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", "beaver"]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("Updated codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("- **Codename**: beaver"), "{content}");
|
||||
}
|
||||
|
||||
/// `create_campaign` writes no Codename line at all, which is every campaign filed before
|
||||
/// the field existed, so the insertion path is the one this command is actually for.
|
||||
/// It lands under the ID, where `campaign add` writes it, so a campaign given a codename
|
||||
/// later is the same file as one filed with it.
|
||||
#[test]
|
||||
fn the_codename_is_inserted_under_the_id_when_the_line_is_absent() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"the fixture changed"
|
||||
);
|
||||
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
let id = content.find("- **ID**:").expect("no id");
|
||||
let codename = content.find("- **Codename**:").expect("no codename");
|
||||
let owner = content.find("- **Owner**:").expect("no owner");
|
||||
assert!(id < codename && codename < owner, "{content}");
|
||||
}
|
||||
|
||||
/// One parser, so a codename is one thing however it was written. The board draws it as a
|
||||
/// label with a mark and no quoting, and that does not depend on which command wrote it.
|
||||
#[test]
|
||||
fn campaign_set_validates_the_codename_the_way_add_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
for value in ["two words", ""] {
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", value]);
|
||||
assert_eq!(out.status.code(), Some(2), "{value:?}: {}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"{value:?} was written"
|
||||
);
|
||||
}
|
||||
|
||||
// And the message is the one `campaign add` gives, since the parser is the same.
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "--codename", "two words"]);
|
||||
assert!(stderr(&out).contains("single word"), "{}", stderr(&out));
|
||||
}
|
||||
|
||||
/// A bare `campaign set <campaign>` is a usage error rather than a silent no-op, exactly
|
||||
/// as it is for `set`.
|
||||
#[test]
|
||||
fn campaign_set_with_no_field_is_a_usage_error() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release"]);
|
||||
assert_eq!(out.status.code(), Some(2), "{}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"something was written"
|
||||
);
|
||||
}
|
||||
|
||||
/// Replacing the title renames the file, keeping the uuid, the way `set --title` does. That
|
||||
/// is the reason this is a `set` rather than a flag on something narrower.
|
||||
#[test]
|
||||
fn campaign_set_renames_the_file_with_the_title() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
// A member first, so the rename has something to break.
|
||||
run(&temp, &["assign", "v1 release", MEMBER]);
|
||||
|
||||
let out = run(
|
||||
&temp,
|
||||
&[
|
||||
"campaign",
|
||||
"set",
|
||||
"v1 release",
|
||||
"--title",
|
||||
"First public release",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
|
||||
let names = campaigns(&worklane);
|
||||
assert!(
|
||||
names.contains(&format!("{CAMP_A}_first-public-release.md")),
|
||||
"not renamed: {names:?}"
|
||||
);
|
||||
assert!(
|
||||
!names.contains(&format!("{CAMP_A}_v1-release.md")),
|
||||
"the old file is still there: {names:?}"
|
||||
);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
// The uuid is kept, so membership survives the rename: it is stored on the member as
|
||||
// the uuid, and nothing has to be rewritten when the campaign is renamed.
|
||||
assert!(content.contains(&format!("- **ID**: {CAMP_A}")), "{content}");
|
||||
let out = run(&temp, &["ls", "--campaign", "First public release"]);
|
||||
assert!(
|
||||
stdout(&out).contains("The member"),
|
||||
"membership was lost: {}",
|
||||
stdout(&out)
|
||||
);
|
||||
}
|
||||
|
||||
/// Both fields in one call, since the group is `multiple`.
|
||||
#[test]
|
||||
fn campaign_set_takes_the_title_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",
|
||||
"-c",
|
||||
"v1",
|
||||
],
|
||||
);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("title, codename"), "{}", stdout(&out));
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.starts_with("# First public release\n"), "{content}");
|
||||
assert!(content.contains("- **Codename**: v1"), "{content}");
|
||||
}
|
||||
|
||||
/// The whole-file comparison `set` and `chown` use, so writing what is already there
|
||||
/// writes nothing and says so.
|
||||
#[test]
|
||||
fn setting_the_codename_a_campaign_already_has_writes_nothing() {
|
||||
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", "-c", "v1"]);
|
||||
|
||||
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");
|
||||
}
|
||||
|
||||
/// A codename set here resolves the campaign afterwards, which is the whole point of the
|
||||
/// field being typable: the tier is in the shared resolver, not in `campaign add`.
|
||||
#[test]
|
||||
fn a_codename_set_afterwards_resolves_the_campaign() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]);
|
||||
|
||||
let out = run(&temp, &["assign", "beaver", MEMBER]);
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(
|
||||
ticket(&worklane, MEMBER).contains(&format!("- **Campaign**: {CAMP_A}")),
|
||||
"{}",
|
||||
ticket(&worklane, MEMBER)
|
||||
);
|
||||
}
|
||||
|
||||
/// Nothing else in the file moves. A campaign carries prose and an owner this command
|
||||
/// cannot reach, and a hand-written section has to survive an edit to a field.
|
||||
#[test]
|
||||
fn content_the_command_cannot_reach_survives_a_set() {
|
||||
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("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"),
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("A handwritten note."), "{content}");
|
||||
assert!(content.contains("What has to ship together."), "{content}");
|
||||
assert!(content.contains("- **Owner**: alice"), "{content}");
|
||||
assert!(!content.contains("**Status**"), "a status was invented: {content}");
|
||||
}
|
||||
|
||||
/// A campaign that does not resolve leaves everything alone, the answer `assign` already
|
||||
/// gives an unknown campaign.
|
||||
#[test]
|
||||
fn an_unknown_campaign_is_refused_and_nothing_is_written() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "nothing-by-that-name", "-c", "v1"]);
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out));
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"something was written"
|
||||
);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_B).contains("Codename"),
|
||||
"something was 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.
|
||||
#[test]
|
||||
fn campaign_set_offers_no_description_and_no_owner() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "--help"]);
|
||||
let help = stdout(&out);
|
||||
|
||||
assert!(help.contains("--codename"), "{help}");
|
||||
assert!(help.contains("--title"), "{help}");
|
||||
assert!(!help.contains("--description"), "{help}");
|
||||
assert!(!help.contains("--owner"), "{help}");
|
||||
assert!(!help.contains("--clear"), "{help}");
|
||||
}
|
||||
|
||||
/// A codename is how a campaign is referred to once it has one: on every card in it and at
|
||||
/// the command line. Replacing that silently is the mistake `install-skill --force` exists
|
||||
/// to prevent, so it is refused and the refusal names the flag.
|
||||
#[test]
|
||||
fn an_existing_codename_is_not_replaced_without_force() {
|
||||
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", "-c", "beaver"]);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
let said = stderr(&out);
|
||||
// Both words and the flag, so the message says what is there, what was asked for and
|
||||
// how to get it.
|
||||
assert!(said.contains("already codenamed 'v1'"), "{said}");
|
||||
assert!(said.contains("'beaver'"), "{said}");
|
||||
assert!(said.contains("--force"), "{said}");
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written anyway");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn force_replaces_an_existing_codename() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "-c", "beaver", "--force"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
let content = campaign_file(&worklane, CAMP_A);
|
||||
assert!(content.contains("- **Codename**: beaver"), "{content}");
|
||||
// The line is replaced, not added beside the old one. Asserted on the field rather
|
||||
// than on the word, since the campaign's title is "v1 release" and holds it too.
|
||||
assert!(!content.contains("- **Codename**: v1"), "the old line survived: {content}");
|
||||
assert_eq!(content.matches("**Codename**").count(), 1, "two codenames: {content}");
|
||||
}
|
||||
|
||||
/// The guard is about overwriting a *different* word. A campaign with no codename has
|
||||
/// nothing to overwrite, so `--force` is not the price of the first one.
|
||||
#[test]
|
||||
fn the_first_codename_needs_no_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
assert!(
|
||||
!campaign_file(&worklane, CAMP_A).contains("Codename"),
|
||||
"the fixture changed"
|
||||
);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
|
||||
}
|
||||
|
||||
/// And setting the one it already has stays a no-op rather than becoming a refusal: there
|
||||
/// is nothing to overwrite, which is the same answer `install-skill` gives an identical
|
||||
/// document.
|
||||
#[test]
|
||||
fn setting_the_same_codename_again_is_a_no_op_not_a_refusal() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "-c", "v1"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(stdout(&out).contains("No changes"), "{}", stdout(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).contains("- **Codename**: v1"));
|
||||
}
|
||||
|
||||
/// Refused before any edit is applied, like `SetArgs::contested`, so a call carrying both
|
||||
/// fields writes neither rather than half of what was asked for.
|
||||
#[test]
|
||||
fn a_refused_codename_takes_the_title_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",
|
||||
"-t",
|
||||
"Renamed anyway",
|
||||
"-c",
|
||||
"beaver",
|
||||
],
|
||||
);
|
||||
|
||||
assert_eq!(out.status.code(), Some(1), "{}", stderr(&out));
|
||||
assert_eq!(campaign_file(&worklane, CAMP_A), before, "the title went through");
|
||||
let names = campaigns(&worklane);
|
||||
assert!(
|
||||
!names.iter().any(|name| name.contains("renamed-anyway")),
|
||||
"renamed: {names:?}"
|
||||
);
|
||||
}
|
||||
|
||||
/// The title needs no guard, since a campaign always has one and replacing it is what the
|
||||
/// flag is for. `--force` is the codename's alone.
|
||||
#[test]
|
||||
fn the_title_is_replaced_without_force() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = board(&temp);
|
||||
run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]);
|
||||
|
||||
let out = run(&temp, &["campaign", "set", "v1", "--title", "First public release"]);
|
||||
|
||||
assert!(out.status.success(), "{}", stderr(&out));
|
||||
assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n"));
|
||||
}
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
/// The tool as this test's binary carries it, so the print path is pinned to the file in
|
||||
/// the repo rather than to a description of it.
|
||||
const TOOL: &str = include_str!("../assets/TOOL.ts");
|
||||
|
||||
/// `XDG_CONFIG_HOME` is redirected, and `HOME` with it, so the suite never writes into
|
||||
/// the config of whoever runs it. Both, because the fallback reads `HOME` and a machine
|
||||
/// that has neither set is not the case under test here.
|
||||
fn run(config: &TempDir, args: &[&str]) -> std::process::Output {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.env("XDG_CONFIG_HOME", config.path())
|
||||
.env("HOME", config.path())
|
||||
.args(args);
|
||||
cmd.assert().get_output().clone()
|
||||
}
|
||||
|
||||
fn installed(config: &TempDir) -> std::path::PathBuf {
|
||||
config.path().join("opencode/tool/worklane.ts")
|
||||
}
|
||||
|
||||
fn stdout(output: &std::process::Output) -> String {
|
||||
String::from_utf8(output.stdout.clone()).unwrap()
|
||||
}
|
||||
|
||||
/// Nothing about the tool needs a board, and it is wanted before there is one.
|
||||
///
|
||||
/// The file name is asserted, not just the directory: opencode names each tool as the
|
||||
/// file then the export, so `worklane.ts` is what makes them `worklane_add` and
|
||||
/// `worklane_mv`.
|
||||
#[test]
|
||||
fn the_tool_installs_outside_a_worklane_directory() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool"]);
|
||||
|
||||
assert!(output.status.success());
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains("Installed the worklane tool"),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// What the message has to carry, and it is not the skills' "next session": opencode
|
||||
/// reads its config once at startup and never reloads it, so a running one keeps the
|
||||
/// tools it began with. The second half is there because the file is executable and
|
||||
/// looks like it needs a toolchain, which it does not.
|
||||
#[test]
|
||||
fn the_tool_says_to_restart_opencode_and_that_nothing_else_is_needed() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Restart it"), "{out}");
|
||||
assert!(out.contains("never reloaded"), "{out}");
|
||||
assert!(out.contains("Nothing else to install"), "{out}");
|
||||
assert!(out.contains("Bun"), "{out}");
|
||||
}
|
||||
|
||||
/// Installing twice is a no-op rather than a rewrite, exactly as `install-skill` is.
|
||||
#[test]
|
||||
fn a_second_install_reports_the_copy_unchanged() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
let out = stdout(&run(&config, &["install-tool"]));
|
||||
|
||||
assert!(out.contains("Already up to date"), "{out}");
|
||||
assert!(!out.contains("Installed the"), "{out}");
|
||||
}
|
||||
|
||||
/// An edited copy is somebody's work, and the refusal names the invocation that shows
|
||||
/// what it would be replaced with. `--print` there and not a skill name: there is one
|
||||
/// tool file, so nothing has to say which.
|
||||
#[test]
|
||||
fn a_modified_copy_is_refused_until_force() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
std::fs::write(installed(&config), "// hand written\n").unwrap();
|
||||
|
||||
let refused = stdout(&run(&config, &["install-tool"]));
|
||||
assert!(refused.contains("Differs from the version in this binary"), "{refused}");
|
||||
assert!(refused.contains("worklane install-tool --print"), "{refused}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), "// hand written\n");
|
||||
|
||||
let forced = stdout(&run(&config, &["install-tool", "--force"]));
|
||||
assert!(forced.contains("Installed the worklane tool"), "{forced}");
|
||||
assert_eq!(std::fs::read_to_string(installed(&config)).unwrap(), TOOL);
|
||||
}
|
||||
|
||||
/// `--print` is for diffing against an installed copy, so it writes nothing.
|
||||
#[test]
|
||||
fn print_writes_the_tool_to_stdout_and_installs_nothing() {
|
||||
let config = TempDir::new().unwrap();
|
||||
let output = run(&config, &["install-tool", "--print"]);
|
||||
|
||||
assert_eq!(stdout(&output), TOOL);
|
||||
assert!(!installed(&config).exists());
|
||||
}
|
||||
|
||||
/// With no `XDG_CONFIG_HOME` the tool lands under `HOME`, which is the same answer
|
||||
/// opencode gives: its config root is `$XDG_CONFIG_HOME/opencode` when that is set and
|
||||
/// `~/.config/opencode` when it is not.
|
||||
#[test]
|
||||
fn the_tool_falls_back_to_the_home_directory_without_xdg_config_home() {
|
||||
let home = TempDir::new().unwrap();
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
let output = cmd
|
||||
.env_remove("XDG_CONFIG_HOME")
|
||||
.env("HOME", home.path())
|
||||
.arg("install-tool")
|
||||
.assert()
|
||||
.success()
|
||||
.get_output()
|
||||
.clone();
|
||||
|
||||
let path = home.path().join(".config/opencode/tool/worklane.ts");
|
||||
assert_eq!(std::fs::read_to_string(&path).unwrap(), TOOL);
|
||||
assert!(
|
||||
stdout(&output).contains(&path.display().to_string()),
|
||||
"{}",
|
||||
stdout(&output)
|
||||
);
|
||||
}
|
||||
|
||||
/// The two commands are independent, which is the whole point of them being two: a
|
||||
/// person on Claude Code takes the skills and never the tool, and one who wants the
|
||||
/// tools is not made to take a second copy of the documents to get them.
|
||||
#[test]
|
||||
fn each_install_command_leaves_the_other_target_alone() {
|
||||
let config = TempDir::new().unwrap();
|
||||
run(&config, &["install-tool"]);
|
||||
|
||||
assert!(installed(&config).exists());
|
||||
assert!(!config.path().join(".claude/skills").exists());
|
||||
|
||||
let skills_only = TempDir::new().unwrap();
|
||||
run(&skills_only, &["install-skill"]);
|
||||
|
||||
assert!(
|
||||
skills_only
|
||||
.path()
|
||||
.join(".claude/skills/worklane/SKILL.md")
|
||||
.exists()
|
||||
);
|
||||
assert!(!installed(&skills_only).exists());
|
||||
}
|
||||
+199
-3
@@ -677,9 +677,9 @@ fn ls_names_the_four_statuses_when_given_another() {
|
||||
}
|
||||
}
|
||||
|
||||
/// The listing reads the fields it prints and nothing else, so the stamps `mv` writes
|
||||
/// do not reach it. Pinned against a ticket carrying one, since a listing that started
|
||||
/// showing them would change the output every board and completion script parses.
|
||||
/// The listing reads the stamps to order the column by them, and prints none of them.
|
||||
/// Pinned against a ticket carrying one, since a listing that started showing them would
|
||||
/// change the output every board and completion script parses.
|
||||
#[test]
|
||||
fn ls_output_is_unchanged_by_a_status_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
@@ -707,3 +707,199 @@ fn ls_output_is_unchanged_by_a_status_stamp() {
|
||||
assert_eq!(after, before);
|
||||
assert!(!after.contains("Committed On"), "{after}");
|
||||
}
|
||||
|
||||
/// A ticket in a status with the entry stamp that status is ordered by, or none.
|
||||
///
|
||||
/// The field is derived from the status rather than passed, so a case says which column
|
||||
/// it is about and cannot name the wrong stamp for it.
|
||||
fn create_stamped_ticket(
|
||||
worklane_dir: &std::path::Path,
|
||||
status: &str,
|
||||
title: &str,
|
||||
uuid: &str,
|
||||
priority: &str,
|
||||
stamp: Option<&str>,
|
||||
) {
|
||||
let field = match status {
|
||||
"committed" => "Committed On",
|
||||
"reviewing" => "Submitted On",
|
||||
"done" => "Completed On",
|
||||
other => panic!("{other} has no entry stamp"),
|
||||
};
|
||||
let line = match stamp {
|
||||
Some(value) => format!("- **{field}**: {value}\n"),
|
||||
None => String::new(),
|
||||
};
|
||||
let body = format!(
|
||||
"# {title}\n\n## Metadata\n\n- **ID**: {uuid}\n- **Priority**: {priority}\n\
|
||||
- **Tags**: test\n- **Due**: _Not set_\n- **Owner**: alice\n{line}\
|
||||
- **Status**: {status}\n"
|
||||
);
|
||||
fs::write(
|
||||
worklane_dir
|
||||
.join(status)
|
||||
.join(format!("{uuid}_{}.md", slug(title))),
|
||||
body,
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
fn positions(stdout: &str, titles: [&str; 3]) -> Vec<usize> {
|
||||
titles
|
||||
.iter()
|
||||
.map(|title| {
|
||||
stdout
|
||||
.find(title)
|
||||
.unwrap_or_else(|| panic!("{title} missing from {stdout}"))
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Committed and reviewing are queues, and the head is what has waited longest: that is
|
||||
/// what the reader picks next from. Priority no longer decides it, which is why the
|
||||
/// oldest here is the least urgent of the three.
|
||||
#[test]
|
||||
fn ls_orders_committed_and_reviewing_by_the_oldest_entry_stamp() {
|
||||
for status in ["committed", "reviewing"] {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("aaaa000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
status,
|
||||
"Middle",
|
||||
&at(3),
|
||||
"1",
|
||||
Some("2026-08-02 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", status]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status}: {stdout}");
|
||||
|
||||
// The overview lists the same columns, so it has to agree with the narrowed
|
||||
// listing rather than falling back to priority for the same tickets.
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).arg("ls");
|
||||
let overview = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&overview, ["Oldest", "Middle", "Newest"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{status} overview: {overview}");
|
||||
}
|
||||
}
|
||||
|
||||
/// Done reads like a changelog: what just landed is at the top. The p1 that finished
|
||||
/// first is at the bottom, which is the whole point of the column not being priority.
|
||||
#[test]
|
||||
fn ls_orders_done_by_the_newest_entry_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("bbbb000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "done", "First", &at(1), "1", Some("2026-08-01 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Last", &at(2), "5", Some("2026-08-03 09:00:00"));
|
||||
create_stamped_ticket(&worklane, "done", "Middle", &at(3), "1", Some("2026-08-02 09:00:00"));
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "done"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Last", "Middle", "First"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// A missing stamp is unknown, not ancient, so it sinks below every stamped ticket
|
||||
/// rather than claiming the head of the queue. Every ticket on a board older than the
|
||||
/// stamps is one of these.
|
||||
#[test]
|
||||
fn ls_sinks_an_unstamped_ticket_below_the_stamped_ones() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("cccc000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(&worklane, "committed", "Unstamped", &at(1), "1", None);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Waited",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"committed",
|
||||
"Fresh",
|
||||
&at(3),
|
||||
"5",
|
||||
Some("2026-08-09 09:00:00"),
|
||||
);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "committed"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Waited", "Fresh", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
/// The two listings are one order. A completion offering candidates in a different
|
||||
/// order than the board prints them would make the head of a column mean two things.
|
||||
#[test]
|
||||
fn ls_ids_prints_the_same_order_the_listing_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
let at = |n: u8| format!("dddd000{n}-0000-0000-0000-000000000001");
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Newest",
|
||||
&at(1),
|
||||
"1",
|
||||
Some("2026-08-03 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(
|
||||
&worklane,
|
||||
"reviewing",
|
||||
"Oldest",
|
||||
&at(2),
|
||||
"5",
|
||||
Some("2026-08-01 09:00:00"),
|
||||
);
|
||||
create_stamped_ticket(&worklane, "reviewing", "Unstamped", &at(3), "1", None);
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing", "--ids"]);
|
||||
let ids = get_stdout(&mut cmd);
|
||||
|
||||
let titles: Vec<&str> = ids.lines().filter_map(|line| line.split('\t').nth(1)).collect();
|
||||
assert_eq!(titles, ["Oldest", "Newest", "Unstamped"], "{ids:?}");
|
||||
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(["ls", "reviewing"]);
|
||||
let stdout = get_stdout(&mut cmd);
|
||||
|
||||
let seen = positions(&stdout, ["Oldest", "Newest", "Unstamped"]);
|
||||
assert!(seen[0] < seen[1] && seen[1] < seen[2], "{stdout}");
|
||||
}
|
||||
|
||||
+103
-13
@@ -923,35 +923,89 @@ fn ticket_at(worklane: &Path, status: &str, filename: &str) -> String {
|
||||
fs::read_to_string(worklane.join(status).join(filename)).unwrap()
|
||||
}
|
||||
|
||||
/// One field per status, written with the time of the move, and only the current one:
|
||||
/// the stamps are where the ticket is now, not the trail of how it got there.
|
||||
/// One field per status, written with the time of the move and added to the ones
|
||||
/// already there: walking the flow leaves the whole journey on the ticket.
|
||||
#[test]
|
||||
fn mv_stamps_the_field_of_the_status_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
for (status, stamp, cleared) in [
|
||||
("committed", "Committed On", "Submitted On"),
|
||||
("reviewing", "Submitted On", "Committed On"),
|
||||
("done", "Completed On", "Submitted On"),
|
||||
// The fixture predates Created At as well as the stamps, and the four reading as
|
||||
// one block is the point, so it is seeded rather than asserted around.
|
||||
let path = worklane.join("backlog").join(&filename);
|
||||
let seeded = fs::read_to_string(&path)
|
||||
.unwrap()
|
||||
.replace("- **Status**:", "- **Created At**: 2026-08-01 09:00:00\n- **Status**:");
|
||||
fs::write(&path, seeded).unwrap();
|
||||
|
||||
let mut carried: Vec<&str> = Vec::new();
|
||||
|
||||
for (status, stamp) in [
|
||||
("committed", "Committed On"),
|
||||
("reviewing", "Submitted On"),
|
||||
("done", "Completed On"),
|
||||
] {
|
||||
let out = move_ticket(&temp, "cccc3333", status, false);
|
||||
assert!(out.status.success(), "{:?}", out);
|
||||
carried.push(stamp);
|
||||
|
||||
let content = ticket_at(&worklane, status, &filename);
|
||||
let value = field(&content, stamp)
|
||||
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
|
||||
|
||||
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
|
||||
assert_eq!(field(&content, cleared), None, "{content}");
|
||||
for stamp in &carried {
|
||||
let value = field(&content, stamp)
|
||||
.unwrap_or_else(|| panic!("no {stamp} after moving to {status}: {content}"));
|
||||
assert!(is_timestamp(&value), "{stamp} reads '{value}'");
|
||||
}
|
||||
}
|
||||
|
||||
// The four side by side and in flow order, which is what a reader asking when this
|
||||
// was filed, picked up, handed over and finished gets one answer each from.
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
let block: Vec<&str> = content
|
||||
.lines()
|
||||
.filter_map(|line| line.strip_prefix("- **"))
|
||||
.filter_map(|line| line.split("**:").next())
|
||||
.skip_while(|name| *name != "Created At")
|
||||
.collect();
|
||||
|
||||
assert_eq!(
|
||||
block,
|
||||
[
|
||||
"Created At",
|
||||
"Committed On",
|
||||
"Submitted On",
|
||||
"Completed On",
|
||||
"Status"
|
||||
],
|
||||
"{content}"
|
||||
);
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own, so a ticket forced back to it carries none at all
|
||||
/// rather than a Completed On for work that has been undone.
|
||||
/// Arrival clears what comes after it and nothing before, so a ticket sent back out of
|
||||
/// done keeps the stages it did get through.
|
||||
#[test]
|
||||
fn mv_removes_the_stamp_of_the_status_it_leaves() {
|
||||
fn mv_removes_the_stamps_of_the_statuses_after_the_one_it_enters() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
for status in ["committed", "reviewing", "done"] {
|
||||
move_ticket(&temp, "cccc3333", status, false);
|
||||
}
|
||||
|
||||
move_ticket(&temp, "cccc3333", "reviewing", true);
|
||||
|
||||
let content = ticket_at(&worklane, "reviewing", &filename);
|
||||
assert_eq!(field(&content, "Completed On"), None, "{content}");
|
||||
assert!(field(&content, "Committed On").is_some(), "{content}");
|
||||
assert!(field(&content, "Submitted On").is_some(), "{content}");
|
||||
}
|
||||
|
||||
/// Backlog has no stamp of its own and every status follows it, so a ticket forced back
|
||||
/// to it carries none at all rather than a Completed On for work that has been undone.
|
||||
#[test]
|
||||
fn mv_back_to_backlog_removes_all_three_stamps() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
@@ -968,6 +1022,42 @@ fn mv_removes_the_stamp_of_the_status_it_leaves() {
|
||||
}
|
||||
}
|
||||
|
||||
/// A skip stamps where it lands and leaves the stages it jumped unwritten: an absent
|
||||
/// field says the ticket never got that far, and inventing one would say it did.
|
||||
#[test]
|
||||
fn mv_skipping_forward_stamps_only_the_target() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
let filename = stamped_ticket(&worklane, "backlog");
|
||||
|
||||
move_ticket(&temp, "cccc3333", "done", true);
|
||||
|
||||
let content = ticket_at(&worklane, "done", &filename);
|
||||
assert!(field(&content, "Completed On").is_some(), "{content}");
|
||||
assert_eq!(field(&content, "Committed On"), None, "{content}");
|
||||
assert_eq!(field(&content, "Submitted On"), None, "{content}");
|
||||
}
|
||||
|
||||
/// The three are `mv`'s alone. Nothing that edits a ticket by hand offers a way to
|
||||
/// write one or take one away, so a stamp is always the record of a real move. Pinned
|
||||
/// so the omission stays a decision rather than becoming an oversight somebody fills in.
|
||||
#[test]
|
||||
fn no_other_command_can_write_or_clear_a_stamp() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
for command in ["add", "set", "append", "chown"] {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args([command, "--help"]);
|
||||
let out = cmd.assert().get_output().clone();
|
||||
let help = String::from_utf8_lossy(&out.stdout).to_lowercase();
|
||||
|
||||
for flag in ["committed-on", "submitted-on", "completed-on", "stamp"] {
|
||||
assert!(!help.contains(flag), "{command} --help names {flag}: {help}");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Re-entry is the time of the move that brought the ticket back, not the first one.
|
||||
#[test]
|
||||
fn mv_restamps_a_status_the_ticket_is_re_entering() {
|
||||
|
||||
@@ -0,0 +1,177 @@
|
||||
//! `worklane tags`, the tag vocabulary.
|
||||
//!
|
||||
//! The command exists because `--tag` answers what carries a tag and cannot answer what
|
||||
//! tags exist, which is the question a grooming sweep starts from. So the properties
|
||||
//! under test are the ones that question needs: every status counted, case kept apart,
|
||||
//! alphabetical order, and an output a shell can parse.
|
||||
|
||||
use assert_cmd::Command;
|
||||
use assert_fs::TempDir;
|
||||
use assert_fs::fixture::{PathChild, PathCreateDir};
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
const BIN_NAME: &str = env!("CARGO_BIN_EXE_worklane");
|
||||
|
||||
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 carrying `tags` verbatim, so a test can write the field the way a hand-made
|
||||
/// ticket would: spaced, unspaced, unset or absent.
|
||||
fn create_ticket(worklane: &Path, status: &str, uuid: &str, tags: &str) {
|
||||
let path = worklane.join(status).join(format!("{uuid}_ticket.md"));
|
||||
fs::write(
|
||||
&path,
|
||||
format!(
|
||||
"# Ticket {uuid}\n\
|
||||
\n\
|
||||
## Description\n\
|
||||
Prose that says **Tags**: not-a-field, in the body.\n\
|
||||
\n\
|
||||
## Metadata\n\
|
||||
\n\
|
||||
- **ID**: {uuid}\n\
|
||||
- **Priority**: 3\n\
|
||||
- **Tags**: {tags}\n\
|
||||
- **Owner**: alice\n\
|
||||
- **Created At**: 2026-08-21 02:10:17\n\
|
||||
- **Status**: {status}\n"
|
||||
),
|
||||
)
|
||||
.unwrap();
|
||||
}
|
||||
|
||||
fn run(temp: &TempDir, args: &[&str]) -> std::process::Output {
|
||||
let mut cmd = Command::cargo_bin(BIN_NAME).unwrap();
|
||||
cmd.current_dir(temp.path()).args(args);
|
||||
cmd.assert().get_output().clone()
|
||||
}
|
||||
|
||||
fn tags(temp: &TempDir) -> Vec<String> {
|
||||
let out = run(temp, &["tags"]);
|
||||
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
|
||||
String::from_utf8_lossy(&out.stdout)
|
||||
.lines()
|
||||
.map(str::to_string)
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Every status, done included, and the count is tickets rather than mentions.
|
||||
#[test]
|
||||
fn tags_counts_every_tag_on_the_board() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug, cli");
|
||||
create_ticket(&worklane, "committed", "22222222", "bug,tui");
|
||||
create_ticket(&worklane, "done", "33333333", "bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t3", "cli\t1", "tui\t1"]);
|
||||
}
|
||||
|
||||
/// Alphabetical, which is the property that makes a near-duplicate findable: the two
|
||||
/// spellings land next to each other.
|
||||
#[test]
|
||||
fn tags_are_alphabetical_so_near_duplicates_are_adjacent() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "tui,bug,bugfix,cli");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1", "bugfix\t1", "cli\t1", "tui\t1"]);
|
||||
}
|
||||
|
||||
/// Case sensitive, like the `--tag` filter. Folding the two together here would hide the
|
||||
/// reason a filter came back short.
|
||||
#[test]
|
||||
fn tags_keeps_case_apart_the_way_the_filter_does() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
create_ticket(&worklane, "backlog", "22222222", "Bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["Bug\t1", "bug\t1"]);
|
||||
|
||||
// And the filter agrees with the listing, which is the point of keeping them apart.
|
||||
let filtered = String::from_utf8_lossy(&run(&temp, &["ls", "--tag", "bug", "--ids"]).stdout)
|
||||
.lines()
|
||||
.count();
|
||||
assert_eq!(filtered, 1);
|
||||
}
|
||||
|
||||
/// An unset field, an absent one and a field of separators are all no tags, the same
|
||||
/// three cases `parse_tags` folds together.
|
||||
#[test]
|
||||
fn tags_ignores_a_ticket_with_nothing_to_count() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
|
||||
create_ticket(&worklane, "backlog", "11111111", "_None_");
|
||||
create_ticket(&worklane, "backlog", "22222222", " , ,");
|
||||
create_ticket(&worklane, "backlog", "33333333", "");
|
||||
// No Tags field at all, the way a hand-made ticket can be.
|
||||
fs::write(
|
||||
worklane.join("backlog").join("44444444_bare.md"),
|
||||
"# Bare\n\n## Metadata\n\n- **ID**: 44444444\n- **Status**: backlog\n",
|
||||
)
|
||||
.unwrap();
|
||||
create_ticket(&worklane, "backlog", "55555555", "real");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["real\t1"]);
|
||||
}
|
||||
|
||||
/// A board with no tags prints nothing rather than a sentence, since a completion reads
|
||||
/// this and a sentence would become a candidate.
|
||||
#[test]
|
||||
fn tags_says_nothing_on_a_board_with_no_tags() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
setup_worklane(&temp);
|
||||
|
||||
let out = run(&temp, &["tags"]);
|
||||
assert!(out.status.success());
|
||||
assert_eq!(String::from_utf8_lossy(&out.stdout), "");
|
||||
}
|
||||
|
||||
/// Unstyled, like `ls --ids`: a shell reads this and an escape sequence would land in
|
||||
/// the candidate.
|
||||
#[test]
|
||||
fn tags_is_unstyled() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
let listing = String::from_utf8_lossy(&run(&temp, &["tags"]).stdout).to_string();
|
||||
assert!(!listing.contains('\u{1b}'), "{listing:?}");
|
||||
}
|
||||
|
||||
/// The Tags line in a Description is prose, not a field, the same rule every other
|
||||
/// metadata read follows.
|
||||
#[test]
|
||||
fn tags_reads_only_the_metadata_section() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
|
||||
/// A missing status directory is skipped rather than refused, as in `ls --ids`: the
|
||||
/// caller is usually a shell, and an error over the prompt is worse than fewer answers.
|
||||
#[test]
|
||||
fn tags_skips_a_missing_status_directory() {
|
||||
let temp = TempDir::new().unwrap();
|
||||
let worklane = setup_worklane(&temp);
|
||||
create_ticket(&worklane, "backlog", "11111111", "bug");
|
||||
fs::remove_dir_all(worklane.join("reviewing")).unwrap();
|
||||
|
||||
assert_eq!(tags(&temp), vec!["bug\t1"]);
|
||||
}
|
||||
Reference in New Issue
Block a user