From 3592584747a7f9f1ccbb90824bde075c719db3cf Mon Sep 17 00:00:00 2001 From: Ansho Rei Date: Mon, 24 Aug 2026 04:53:49 +0200 Subject: [PATCH] Edit a campaign's description, and bump to 0.27.0 `campaign set` reached the title and the codename, so the description a campaign was filed with was the description it kept: fixing a typo in the one field nothing could edit meant a hand edit of the file, or refiling the campaign and reassigning every member. Both halves arrive together, which is why d637288 left this out rather than adding the flag. `campaign set --description` replaces the section and `campaign append --description` adds a paragraph to it, because a `set` with no `append` is the half that is easy to reach for and wrong: replacing a description to add a sentence is how the rest of it gets lost. `append` is a campaign's own subcommand rather than the top-level one, which resolves a ticket. `resolve_in`'s tiers are the same over both directories, so one positional naming either object could resolve in each with nothing but a flag to say which was meant, and it would make a liar of the explanation `resolve_ticket` gives a ticket search that names a campaign. The section is the `DESCRIPTION` entry and the surgery is `set_section_body`, `append_section_body` and `Section::normalise`, not a copy scoped to campaigns. `SECTION_ORDER` needs no campaign variant: a campaign holds one section where a ticket holds four, and the followers a campaign does not have are simply not in the file, so its description anchors against `## Metadata`, where `campaign_body` writes it. Still no `--clear`, and that is now a decision rather than a deferral: a campaign's description has no cleared form, so an empty `--description ""` is a paragraph break here as it is everywhere else, and the refusal for an all-blank value says there is nowhere to go back to instead of naming a flag that does not exist. `replaced_items` and `appended_items` hold that check once for both objects, with the way out as the caller's argument. The section refusal no longer says "Ticket", since a campaign reaches it too. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 10 +- Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 3 +- assets/PLAN.md | 9 +- assets/SKILL.md | 16 +- src/command.rs | 79 ++++++-- src/completions.rs | 20 +- src/handlers.rs | 106 ++++++++-- src/main.rs | 1 + src/util.rs | 10 +- tests/cmd_campaign.rs | 450 +++++++++++++++++++++++++++++++++++++++++- 12 files changed, 652 insertions(+), 56 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6208d0e..158e4f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,6 +125,7 @@ and this file is for what someone changing worklane's own code needs. - Appending to a numbered section continues from the count of steps already there and does not renumber what is above it, so a handwritten line in the section survives exactly as written - Appending to an empty section replaces the placeholder rather than following it, or the ticket would read `_No description provided._` above its description - An empty value is a paragraph break for the three sections and a usage error for the scalars, via `non_empty` and `clearable` in `command.rs`. Neither spells clearing, and both errors name the flag that does +- **A call whose values are *every one* blank is refused, by `replaced_items` for `set` and `appended_items` for `append`.** The check is the section's rather than the object's, so `campaign set --description` shares it. What differs is the way out, which is why `replaced_items` takes it as an argument: a ticket's section is emptied with `--clear ` and a campaign's description cannot be emptied at all, so a single hard-coded tail would name a flag that does not exist on one of the two ### Clearing a Field - **`set --clear ` is the one way to take a value away, and it is a flag with the field as its value.** Not a per-field `--clear-due`, which is a flag per field to keep in step with the field it undoes, and not an empty value, which is already a paragraph break for a section and would make an accidentally empty variable a silent delete. Repeatable, so one call empties as many fields as it likes @@ -185,9 +186,14 @@ and this file is for what someone changing worklane's own code needs. - `campaign ls` scans the status directories **once per campaign** to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice - **The TUI got a card label and a frame, not a campaign tab.** 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups *across* the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and `c` for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in `columns_of` and is what names the label; see The Board View - **A campaign is named by its codename on the board, and by its short id when it has none.** The uuid does not fit on a card and the title is a sentence, which is the gap `Codename` fills. `campaign_label` builds it in one place, as a `Cell`, so the CLI paints it and the board makes a span of it; the mark is `CAMPAIGN_MARK`, `~`, beside `#` for a tag -- **`campaign set` is the only writer of a filed campaign's fields, and it carries the two scalars.** d637288 decided it: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `--title`, which renames the file the way `set --title` does, and `--codename`. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist +- **`campaign set` and `campaign append` are the only writers of a filed campaign's fields.** d637288 decided the command: a `set` rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. `set` carries `--title`, which renames the file the way `set --title` does, `--description` and `--codename`; `append` carries `--description` alone. `campaign add` writing a field at creation is not a second writer, exactly as `add --title` and `set --title` coexist - **Replacing a codename the campaign already has needs `--force`.** Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake `install-skill --force` exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like `SetArgs::contested`, so a call also carrying `--title` writes neither field. Setting the codename a campaign already carries stays a **no-op, not a refusal** — `--force` is about overwriting a *different* word, which is the same division `install::Outcome` draws between `Unchanged` and `Refused`. `--force` guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required -- **No `campaign set --description`, and that is the line, not an oversight.** `set` and `append` are a pair for a prose section: a way to replace a description with no way to add a paragraph is half of it. The two scalars have no append form at all, which is the same line `append` already draws for a ticket. `campaign_set_offers_no_description_and_no_owner` pins it. No `--owner` either, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign; and no `--clear`, because a wrong codename is replaced rather than emptied and `Clearable` is `SetArgs`'s, its variants being a ticket's fields +- **The description arrived as a pair, `set --description` and `campaign append`, 32e98ab.** Never one without the other: for a prose section `set` replaces and `append` adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line `append` already draws for a ticket, and `campaign_append_offers_only_the_description` pins that. Neither flag takes `--force`: a description is prose written to be revised, the same reason `tags set --annotation` has none +- **`append` is a campaign's own subcommand, not the top-level `append`.** That one resolves a ticket, and one positional naming either object is the ambiguity `resolve_in` makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of `resolve_ticket`, which explains a ticket search that *names* a campaign. Under `campaign` the object is settled by the command, as it is for `set`, `show` and `ls` +- **Still no `--owner` and still no `--clear`.** No `--owner`, because nothing writes a campaign's Owner today and giving `set` one would settle by accident whether `chown` grows a campaign. No `--clear`, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be `Clearable` on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. `campaign_set_offers_no_owner_and_no_clear` pins both +- **An empty `--description ""` is a paragraph break here too, and the refusal for an all-blank value names no flag.** Every prose argument in the tool reads a blank value that way, `add`, `set` and `tags --annotation` alike, so a campaign reading it as *empty the section* would be the one exception. With no `--clear` to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. `replaced_items` is where the check lives, shared with `set`, and the way out is the caller's argument for exactly that reason +- **`SECTION_ORDER` needs no campaign variant, and that is what the one-section file proves.** A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, *filtered by what is actually in the file*, so a campaign's description anchors against `## Metadata` — which is where `campaign_body` writes it. `the_description_is_edited_in_place_in_a_file_with_one_section` pins that no section a campaign does not have gets inserted to anchor against +- **A campaign whose Description heading is gone is refused, not given the section back.** No `ensure_section` on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where `add` writes nothing and the insertion is the only path there is. The refusal therefore names the section and **not** the object — "There is no description section to write to" — because both a ticket and a campaign reach `replace_section_body` now. `write_then_replace` still carries the noun, where the message is about a file - **The codename is written through `set_or_insert_metadata_field`, not `set_metadata_field`.** Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts `assign` on the upsert. **`Codename` is therefore in `METADATA_ORDER`, directly after ID**, so an inserted one lands where `campaign_body` writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing - **One write path for tickets and campaigns.** `save_entry` is the body, `save_ticket` and `save_campaign` are the named wrappers, and `write_then_replace` and `find_entry_file` take the noun as a `&str` so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, `_.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 diff --git a/Cargo.lock b/Cargo.lock index 9abc65a..369c6ad 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.26.4" +version = "0.27.0" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index be7d38c..24f13b3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.26.4" +version = "0.27.0" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 89b0da1..b4363bd 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ Worklane is a local Kanban flow for agentic software development. | `worklane uncheck [criteria...]` | Unticks acceptance criteria, addressed the same way | | `worklane comment ` | 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 ` | 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 set ` | Replaces `--title`, which renames the file keeping the uuid, `--description` and `--codename`. At least one required. The way a campaign filed before codenames existed gets one, and the way a description filed with a typo in it gets fixed. Replacing a codename the campaign already has needs `--force`, since that is the word it is referred to by everywhere; setting the one it already has is a no-op either way. A description needs no `--force`: it is prose written to be revised. No `--clear` and no `--owner` | +| `worklane campaign append ` | Adds a paragraph to a campaign's description with `--description`, which is required. The other half of `campaign set --description`, so adding a line to a description does not mean retyping the rest of it. Repeat the flag for more lines within the one paragraph. Its own subcommand rather than the top-level `append`, which resolves a ticket | | `worklane campaign ls` | Lists the campaigns as their short id, their codename, their title 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 ` | 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 ` | 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 | diff --git a/assets/PLAN.md b/assets/PLAN.md index 5dfa238..3ae2ac6 100644 --- a/assets/PLAN.md +++ b/assets/PLAN.md @@ -168,7 +168,8 @@ fields; a goal is a campaign. worklane campaign ls worklane campaign show v1 worklane campaign add --title "..." --codename v1 --description "..." -worklane campaign set v1 --title "..." # or --codename, on one already filed +worklane campaign set v1 --title "..." # or --description or --codename, on one already filed +worklane campaign append v1 -d "..." # add a paragraph to the description worklane assign v1 1b78a24 ``` @@ -194,6 +195,12 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag. - **Do not propose renaming a codename a campaign already has.** It is what the campaign is called on every card in it and at the command line, so changing it is churn dressed as grooming. `campaign set` refuses it without `--force` for that reason. +- **A campaign's description is editable, so a wrong one is a fix rather than a refiling.** + A container whose description no longer describes what its members are for is worth + pointing out: it is the line every one of those tickets was filed against. `campaign set + --description` replaces it and `campaign append --description` adds to it, so neither + needs the campaign refiled and its members reassigned. Adding to it is the usual answer; + replacing prose to add a sentence to it is how the rest of it gets lost. Proposing a campaign means naming the goal, the members, and what is deliberately left out of it. The last part is what makes it a goal rather than a pile. diff --git a/assets/SKILL.md b/assets/SKILL.md index a399440..10d94e5 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -211,7 +211,8 @@ worklane campaign add --title "First public release" --codename v1 \ worklane campaign ls # every campaign, its codename, how far it has got worklane campaign ls --ids # id and title, tab separated, like ls --ids worklane campaign show v1 # its body, then its members by status -worklane campaign set v1 --title "..." # replace the title or the codename +worklane campaign set v1 --title "..." # replace the title, description or codename +worklane campaign append v1 -d "..." # add a paragraph to the description worklane assign v1 1b78a24 # put a ticket in it worklane ls --campaign v1 # only that campaign's tickets ``` @@ -226,9 +227,16 @@ existed needs. **Replacing a codename it already has needs `--force`**: that wor the campaign is referred to on the board and at the command line, so changing it is a decision rather than a correction. Setting the one it already has is a no-op either way. -`campaign set` is the only way to change a campaign after it is filed, and it reaches the -title and the codename only. There is no way to edit a campaign's description or its owner -yet. +`campaign set` and `campaign append` are the only ways to change a campaign after it is +filed. `set` replaces the title, the description or the codename; `append` adds a paragraph +to the description, which is what to use when the description is right and only incomplete, +since replacing prose to add a sentence to it is how the rest of it gets lost. An empty +`--description ""` between two values is a paragraph break, exactly as it is for a ticket, +and a call whose every value is blank is refused: a campaign's description cannot be +emptied. There is still no way to change a campaign's owner. + +`append` here is `campaign append` and not the top-level `append`, which takes a ticket. The +two objects are addressed the same way, so the command is what says which one is meant. `assign` takes the **campaign first and the ticket second**, like `chown`, and is the only writer of the field. `add` has no `--campaign` and neither has `set`, so membership diff --git a/src/command.rs b/src/command.rs index af7142d..cc991a0 100644 --- a/src/command.rs +++ b/src/command.rs @@ -358,10 +358,18 @@ pub enum Command { /// No `mv`: a campaign has no status to move it to, its state is derived from its /// members. /// -/// No `append`, and therefore no `set --description`: `set` and `append` are a pair for a -/// prose section, and a way to replace a description with no way to add a paragraph to one -/// is half of it. That pair is its own ticket. `set` here carries the two scalars, which -/// have no append form at all, the same line `append` already draws for a ticket. +/// `set` and `append` arrive together, 32e98ab, because for a prose section they are a +/// pair: a way to replace a description with no way to add a paragraph to one is the half +/// that is easy to reach for and wrong, since replacing a description to add a sentence is +/// how the rest of it gets lost. The two scalars have no append form at all, which is the +/// same line `append` already draws for a ticket. +/// +/// **`append` is a campaign's own subcommand and not the top-level `append`.** That one +/// resolves a ticket, and its positional would then name either object: `resolve_in`'s tiers +/// are the same over both directories, so a search can resolve in each and nothing but a +/// flag could say which was meant. It would also make a liar of `resolve_ticket`, which +/// explains a ticket search that names a campaign. Under `campaign` the object is settled by +/// the command, the way it is for `set`, `show` and `ls`. #[derive(clap::Subcommand)] pub enum CampaignCommand { /// File a new campaign @@ -369,11 +377,19 @@ pub enum CampaignCommand { /// Replace fields on an existing campaign /// - /// The only way to change a campaign after it is filed. `campaign add --codename` writes - /// the field at creation the way `add --title` does for a ticket; this is what replaces - /// it, so every campaign filed before the field existed can still be given one. + /// The only way to change a campaign's title or codename after it is filed. + /// `campaign add --codename` writes the field at creation the way `add --title` does for + /// a ticket; this is what replaces it, so every campaign filed before the field existed + /// can still be given one. Set(CampaignSetArgs), + /// Add a paragraph to a campaign's description + /// + /// The other half of `campaign set --description`, and the half that keeps what is + /// already written: a description is the sentence a whole campaign's members are filed + /// against, so adding a line to it must not mean retyping it. + Append(CampaignAppendArgs), + /// List campaigns with their member counts Ls { /// Print one campaign per line as its id and title, tab separated, for a script @@ -394,25 +410,30 @@ pub enum CampaignCommand { }, } -/// What can be replaced on a campaign that is already filed: its title and its codename. -/// -/// The two scalars, and deliberately not the description. See [`CampaignCommand`]. +/// What can be replaced on a campaign that is already filed: everything it holds but its +/// owner. /// /// No `--owner`: nothing writes a campaign's Owner today, and giving `set` one would settle /// by accident whether `chown` grows a campaign or `set` keeps the field, which is the /// one-field-one-writer question and not this command's to answer. /// -/// No `--clear`: nothing has asked to empty a codename, a wrong one is replaced rather than -/// emptied, and the vocabulary is a real question — `Clearable` is `SetArgs`'s and its -/// variants are a ticket's fields, so reusing it here would put a ticket's enum on a -/// campaign and inventing a second one is a decision worth making on purpose. +/// No `--clear`, which is 32e98ab's decision and not a deferral. A codename is replaced +/// rather than emptied, and a campaign's one prose section has no cleared form worth +/// reaching: emptying the description of a container six tickets are filed against is not a +/// thing anybody has asked for, and the only ways to spell it would be to put [`Clearable`] +/// on a campaign, whose variants are a ticket's fields, or to invent a second enum with one +/// variant in it. So an empty `--description ""` stays a paragraph break here exactly as it +/// is everywhere else, and the refusal for an all-blank value says there is nowhere to go +/// back to rather than naming a flag that does not exist. /// /// `--force` guards the codename and nothing else. A campaign that already has one is /// referred to by it: it is on every card in the campaign, it is what resolves it at the /// command line, and it is very likely in somebody's shell history. Replacing that silently /// is the same mistake overwriting an edited skill document would be, which is what /// `install-skill --force` exists for. A title needs no guard, since a campaign always has -/// one and replacing it is the whole point of the flag. +/// one and replacing it is the whole point of the flag. Neither does a description: it is +/// prose written to be revised, the same reason `tags set --annotation` has no guard, and a +/// guard in front of the command's whole purpose is worse than no command. /// /// The group makes at least one field mandatory, so a bare `worklane campaign set ` is a /// usage error rather than a silent no-op, exactly as it is for [`SetArgs`]. @@ -421,7 +442,7 @@ pub enum CampaignCommand { clap::ArgGroup::new("campaign_set_fields") .required(true) .multiple(true) - .args(["title", "codename"]) + .args(["title", "description", "codename"]) ))] pub struct CampaignSetArgs { /// Campaign UUID, title, filename or codename @@ -431,6 +452,13 @@ pub struct CampaignSetArgs { #[arg(short, long, allow_hyphen_values = PROSE, value_parser = non_empty)] pub title: Option, + /// Replace the description. Repeat the flag for more lines, empty for a paragraph break + /// + /// The whole section, so a paragraph added to it is `campaign append --description` + /// rather than the description retyped + #[arg(short, long, allow_hyphen_values = PROSE)] + pub description: Vec, + /// Replace the codename, a single word to call the campaign by /// /// The same parser `campaign add --codename` takes, so a codename is one thing however @@ -449,6 +477,25 @@ pub struct CampaignSetArgs { pub force: bool, } +/// What can be added to a campaign that is already filed: a paragraph of its description. +/// +/// One field, so it is `required` rather than a group of one, which is the longer way to say +/// the same thing and the shape [`TagSetArgs`] already takes. A bare +/// `worklane campaign append ` is therefore a usage error rather than a silent no-op. +/// +/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is +/// the line `append` already draws for a ticket, where the title is absent for the same +/// reason. +#[derive(clap::Args)] +pub struct CampaignAppendArgs { + /// Campaign UUID, title, filename or codename + pub campaign: String, + + /// Add a paragraph to the description. Repeat the flag for more lines within it + #[arg(short, long, required = true, allow_hyphen_values = PROSE)] + pub description: Vec, +} + /// What a campaign holds: a title, a description and an owner. /// /// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a diff --git a/src/completions.rs b/src/completions.rs index 843281a..6122d13 100644 --- a/src/completions.rs +++ b/src/completions.rs @@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"]; /// Nested subcommands whose first argument is a campaign, as `parent child`. /// -/// `campaign show` and `campaign set`, and they are why the fish half needs a third -/// position helper: their argument is the *third* token, where `__worklane_first_arg_of` -/// reads the second and `__worklane_second_arg_of` counts a top-level command's arguments. -/// Neither can tell `campaign show ` from `chown alice ` by position. -pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 2] = [("campaign", "show"), ("campaign", "set")]; +/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half +/// needs a third position helper: their argument is the *third* token, where +/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a +/// top-level command's arguments. Neither can tell `campaign show ` from +/// `chown alice ` by position. +pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [ + ("campaign", "show"), + ("campaign", "set"), + ("campaign", "append"), +]; /// Options whose value is a campaign. pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"]; @@ -374,7 +379,10 @@ mod tests { // A guard on the walker itself: if it stopped finding arguments, every assertion // above would pass by never running. - assert_eq!(seen, 4, "expected assign, campaign show, campaign set and ls --campaign"); + assert_eq!( + seen, 5, + "expected assign, campaign show, campaign set, campaign append and ls --campaign" + ); } /// Commands whose tag positional names a tag that does not exist yet. diff --git a/src/handlers.rs b/src/handlers.rs index 16c361a..c2b66b1 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -7,8 +7,8 @@ use std::path::Path; use crate::campaign::*; use crate::command::{ - AddArgs, AppendArgs, CampaignAddArgs, CampaignSetArgs, CheckArgs, ChownArgs, LsArgs, - RelateArgs, SetArgs, TagAddArgs, TagSetArgs, + AddArgs, AppendArgs, CampaignAddArgs, CampaignAppendArgs, CampaignSetArgs, CheckArgs, + ChownArgs, LsArgs, RelateArgs, SetArgs, TagAddArgs, TagSetArgs, }; use crate::install; use crate::tag::{TAGS_FILE, TagIndex, tags_path}; @@ -784,6 +784,42 @@ fn section_args<'a>( ] } +/// The lines a caller's values amount to, or the refusal an all-blank call earns. +/// +/// An empty value is a paragraph break, so a call whose values are *every one* blank asked +/// for nothing, and writing an empty section is not what it meant. Shared by `set` and +/// `campaign set` because the rule is the section's rather than the object's. +/// +/// `instead` is the way out, and it is the caller's because the callers differ: a ticket's +/// section is emptied with `--clear `, and a campaign's description has no cleared +/// form at all, per [`CampaignSetArgs`]. +fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result> { + let items = section.normalise(values); + if items.is_empty() { + return Err(anyhow!( + "An empty value is a paragraph break, not a way to empty the {}: {}", + section.label, + instead + )); + } + + Ok(items) +} + +/// The same for `append`, which has no way out to name: appending nothing was never a way +/// to empty anything, so the message says only that there was nothing to add. +fn appended_items(section: &Section, values: &[String]) -> Result> { + let items = section.normalise(values); + if items.is_empty() { + return Err(anyhow!( + "Nothing to append to the {}: every value given was blank", + section.label + )); + } + + Ok(items) +} + /// Write the ticket back, renaming the file when a new title changes its slug. /// /// The content goes down first and the rename second, the same order and for the same @@ -917,14 +953,8 @@ pub fn cmd_set(args: &SetArgs, start: &Path) -> Result<()> { continue; } - let items = section.normalise(values); - if items.is_empty() { - return Err(anyhow!( - "An empty value is a paragraph break, not a way to empty the {}: use --clear {}", - section.label, - section.clear.map_or("", Clearable::name) - )); - } + let clear = format!("use --clear {}", section.clear.map_or("", Clearable::name)); + let items = replaced_items(section, values, &clear)?; let next = set_section_body(&content, section, &items)?; apply(&mut content, &mut changed, section.label, next); @@ -1031,13 +1061,7 @@ pub fn cmd_append(args: &AppendArgs, start: &Path) -> Result<()> { continue; } - let items = section.normalise(values); - if items.is_empty() { - return Err(anyhow!( - "Nothing to append to the {}: every value given was blank", - section.label - )); - } + let items = appended_items(section, values)?; content = append_section_body(&content, section, &items)?; changed.push(section.label); @@ -1409,6 +1433,18 @@ pub fn cmd_tag_set(args: &TagSetArgs, start: &Path) -> Result<()> { /// No-op detection compares the whole file, the way `set` and `chown` do, so setting a /// codename a campaign already carries writes nothing. That is a no-op and not a refusal: /// `--force` is about overwriting a *different* word, and there is nothing to overwrite. +/// +/// **The description goes through `set_section_body` and the `DESCRIPTION` entry**, the +/// section table `cmd_set` and `campaign_body` already read, so what a campaign's one prose +/// section *is* stays decided in one place. A second definition scoped to campaigns would +/// drift on the spelling of the heading, which is the drift `campaign_body` was written +/// against. +/// +/// A campaign whose Description heading is gone is refused by that call rather than given +/// the section back through `ensure_section`. Every campaign the tool has ever filed carries +/// the heading, so an insertion path here would be reachable only from a hand-edited file: +/// that is the opposite of the Relations case, where `add` writes nothing and the insertion +/// is the only path there is. pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> { let worklane_dir = find_worklane_dir(start)?; let campaign = resolve_campaign(&args.campaign, &worklane_dir)?; @@ -1436,6 +1472,16 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> { apply(&mut content, &mut changed, "title", next); } + if !args.description.is_empty() { + let items = replaced_items( + &DESCRIPTION, + &args.description, + "a campaign's description has no cleared form", + )?; + let next = set_section_body(&content, &DESCRIPTION, &items)?; + apply(&mut content, &mut changed, DESCRIPTION.label, next); + } + if let Some(codename) = &args.codename { let next = set_or_insert_metadata_field(&content, CODENAME_FIELD, codename, &title)?; apply(&mut content, &mut changed, "codename", next); @@ -1453,6 +1499,32 @@ pub fn cmd_campaign_set(args: &CampaignSetArgs, start: &Path) -> Result<()> { Ok(()) } +/// Add a paragraph to a campaign's description. +/// +/// The other half of `campaign set --description`, and `cmd_append` for a campaign: the same +/// `append_section_body` and the same `DESCRIPTION` entry, so a paragraph lands under a +/// campaign's description the way it lands under a ticket's, blank line and all. A campaign +/// filed with no description holds the placeholder, and that is replaced rather than +/// followed, which is `append_section_body`'s rule and not a case handled here. +/// +/// No whole-file comparison, unlike `set`: every value blank is refused above, so there is +/// nothing left that appends nothing. `cmd_append` says it the same way. +/// +/// One section, so there is no loop and no list to report: what changed is the description +/// or the call failed. +pub fn cmd_campaign_append(args: &CampaignAppendArgs, start: &Path) -> Result<()> { + let worklane_dir = find_worklane_dir(start)?; + let campaign = resolve_campaign(&args.campaign, &worklane_dir)?; + + let items = appended_items(&DESCRIPTION, &args.description)?; + let content = append_section_body(&campaign.content, &DESCRIPTION, &items)?; + + save_campaign(&worklane_dir, &campaign.uuid, &campaign.title, None, &content)?; + + report(&[DESCRIPTION.label], &campaign.title, "Appended to"); + Ok(()) +} + /// Show a campaign, then its members grouped by status. /// /// Every status is shown, done included, unlike `ls`, which leaves done out of its diff --git a/src/main.rs b/src/main.rs index 80e97b4..2aff9ff 100644 --- a/src/main.rs +++ b/src/main.rs @@ -73,6 +73,7 @@ fn main() -> Result<()> { cmd_campaign_ls(&worklane_dir, ids) } CampaignCommand::Set(args) => cmd_campaign_set(&args, &start), + CampaignCommand::Append(args) => cmd_campaign_append(&args, &start), CampaignCommand::Show { campaign } => { let worklane_dir = find_worklane_dir(&start)?; cmd_campaign_show(&campaign, &worklane_dir) diff --git a/src/util.rs b/src/util.rs index 6f21746..3c69f52 100644 --- a/src/util.rs +++ b/src/util.rs @@ -1843,6 +1843,12 @@ pub fn clear_section_body(content: &str, section: &Section) -> Result { } /// The line surgery both of the above are, given a body that is already rendered. +/// +/// The refusal names the section and not the file it is missing from, because both a ticket +/// and a campaign reach here: `campaign set --description` writes a campaign's one prose +/// section through this, so "Ticket has no description section" would be wrong half the +/// time. `write_then_replace` carries the noun instead, where a message about a *file* is +/// worth spelling. fn replace_section_body( content: &str, section: &Section, @@ -1850,7 +1856,7 @@ fn replace_section_body( ) -> Result { let lines: Vec<&str> = content.lines().collect(); let body = section_body(&lines, section.heading) - .ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?; + .ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?; let mut out: Vec = lines[..body.start].iter().map(|l| l.to_string()).collect(); out.extend(body_lines); @@ -1871,7 +1877,7 @@ fn replace_section_body( pub fn append_section_body(content: &str, section: &Section, items: &[String]) -> Result { let lines: Vec<&str> = content.lines().collect(); let body = section_body(&lines, section.heading) - .ok_or_else(|| anyhow!("Ticket has no {} section", section.label))?; + .ok_or_else(|| anyhow!("There is no {} section to write to", section.label))?; let at = body_content_end(&lines, &body); let existing: Vec<&&str> = lines[body.start..at] diff --git a/tests/cmd_campaign.rs b/tests/cmd_campaign.rs index c6192f5..f4e1637 100644 --- a/tests/cmd_campaign.rs +++ b/tests/cmd_campaign.rs @@ -1129,11 +1129,13 @@ fn an_unknown_campaign_is_refused_and_nothing_is_written() { ); } -/// No `--description`: `set` and `append` are a pair for a prose section, and a way to -/// replace a description with no way to add a paragraph is half of it. Pinned so the -/// omission stays a decision rather than becoming an oversight somebody fills in. +/// `--description` arrived with `campaign append`, 32e98ab, because for a prose section the +/// two are a pair. What is still deliberately absent is what this pins: no `--owner`, which +/// would settle by accident whether `chown` grows a campaign, and no `--clear`, because a +/// campaign's description has no cleared form and `Clearable`'s variants are a ticket's +/// fields. #[test] -fn campaign_set_offers_no_description_and_no_owner() { +fn campaign_set_offers_no_owner_and_no_clear() { let temp = TempDir::new().unwrap(); setup_worklane(&temp); @@ -1142,7 +1144,7 @@ fn campaign_set_offers_no_description_and_no_owner() { assert!(help.contains("--codename"), "{help}"); assert!(help.contains("--title"), "{help}"); - assert!(!help.contains("--description"), "{help}"); + assert!(help.contains("--description"), "{help}"); assert!(!help.contains("--owner"), "{help}"); assert!(!help.contains("--clear"), "{help}"); } @@ -1263,3 +1265,441 @@ fn the_title_is_replaced_without_force() { assert!(out.status.success(), "{}", stderr(&out)); assert!(campaign_file(&worklane, CAMP_A).starts_with("# First public release\n")); } + +// ---------------------------------------------- campaign set --description -- + +/// The point of 32e98ab: the description a campaign was filed with is no longer the one it +/// keeps. `create_campaign` writes prose, so this is a replacement rather than a first line. +#[test] +fn campaign_set_replaces_the_description() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + let out = run( + &temp, + &[ + "campaign", + "set", + "v1 release", + "--description", + "What the tag has to hold.", + ], + ); + assert!(out.status.success(), "{}", stderr(&out)); + assert!(stdout(&out).contains("Updated description"), "{}", stdout(&out)); + + let content = campaign_file(&worklane, CAMP_A); + assert!(content.contains("What the tag has to hold."), "{content}"); + assert!( + !content.contains("What has to ship together."), + "the old description survived: {content}" + ); +} + +/// An empty value between two others is the paragraph break, the rule every prose argument +/// in the tool follows: `add --description`, `set --description` and `tags --annotation`. +#[test] +fn an_empty_value_is_a_paragraph_break_in_a_campaigns_description() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + let out = run( + &temp, + &[ + "campaign", + "set", + "v1 release", + "-d", + "The tag itself.", + "-d", + "", + "-d", + "And what blocks it.", + ], + ); + assert!(out.status.success(), "{}", stderr(&out)); + + let content = campaign_file(&worklane, CAMP_A); + assert!(content.contains("The tag itself.\n\nAnd what blocks it."), "{content}"); +} + +/// And an all-blank value is refused rather than emptying the section. The refusal names no +/// flag, because there is none: a campaign's description has no cleared form, which is the +/// `Clearable` question 32e98ab settled rather than deferred. +#[test] +fn an_all_blank_description_is_refused_and_names_no_clear_flag() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + let before = campaign_file(&worklane, CAMP_A); + + let out = run(&temp, &["campaign", "set", "v1 release", "-d", "", "-d", " "]); + + assert_eq!(out.status.code(), Some(1), "{}", stderr(&out)); + let said = stderr(&out); + assert!(said.contains("An empty value is a paragraph break"), "{said}"); + assert!(said.contains("no cleared form"), "{said}"); + assert!(!said.contains("--clear"), "it named a flag that does not exist: {said}"); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written"); +} + +/// The whole-file comparison `set`, `chown` and the codename already use, so a description +/// replaced with the one it already holds writes nothing. +#[test] +fn setting_the_description_a_campaign_already_has_writes_nothing() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + let before = campaign_file(&worklane, CAMP_A); + + let out = run( + &temp, + &[ + "campaign", + "set", + "v1 release", + "-d", + "What has to ship together.", + ], + ); + + assert!(out.status.success(), "{}", stderr(&out)); + assert!(stdout(&out).contains("No changes"), "{}", stdout(&out)); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was rewritten"); +} + +/// Three fields in one call, since the group is `multiple` and the description is in it. +#[test] +fn campaign_set_takes_the_title_the_description_and_the_codename_together() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + let out = run( + &temp, + &[ + "campaign", + "set", + "v1 release", + "-t", + "First public release", + "-d", + "What the tag has to hold.", + "-c", + "v1", + ], + ); + assert!(out.status.success(), "{}", stderr(&out)); + assert!(stdout(&out).contains("title, description, codename"), "{}", stdout(&out)); + + let content = campaign_file(&worklane, CAMP_A); + assert!(content.starts_with("# First public release\n"), "{content}"); + assert!(content.contains("What the tag has to hold."), "{content}"); + assert!(content.contains("- **Codename**: v1"), "{content}"); +} + +/// A refused codename takes the description down with it, the way it already takes the +/// title: checked before any edit is applied, so a call writes all of what it asked for or +/// none of it. +#[test] +fn a_refused_codename_takes_the_description_down_with_it() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]); + let before = campaign_file(&worklane, CAMP_A); + + let out = run( + &temp, + &[ + "campaign", + "set", + "v1", + "-d", + "Rewritten anyway.", + "-c", + "beaver", + ], + ); + + assert_eq!(out.status.code(), Some(1), "{}", stderr(&out)); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "the description went through"); +} + +// ---------------------------------------------------------- campaign append -- + +/// The other half of the pair, and the reason `set --description` is not a flag on its own: +/// adding a line to a description must not mean retyping the rest of it. +#[test] +fn campaign_append_adds_a_paragraph_without_replacing_the_description() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + let out = run( + &temp, + &[ + "campaign", + "append", + "v1 release", + "-d", + "And what is out of scope.", + ], + ); + assert!(out.status.success(), "{}", stderr(&out)); + assert!(stdout(&out).contains("Appended to description"), "{}", stdout(&out)); + + let content = campaign_file(&worklane, CAMP_A); + // The paragraph lands after the one that was there, with the blank line between them + // that makes it a paragraph rather than a run-on. + assert!( + content.contains("What has to ship together.\n\nAnd what is out of scope.\n"), + "{content}" + ); +} + +/// Several values in one call are lines *within* the paragraph, not several paragraphs. The +/// same reading `append --description` gives a ticket, since it is the same section entry. +#[test] +fn the_values_of_one_append_are_lines_within_the_paragraph() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + run( + &temp, + &[ + "campaign", + "append", + "v1 release", + "-d", + "Out of scope:", + "-d", + "the installer.", + ], + ); + + let content = campaign_file(&worklane, CAMP_A); + assert!(content.contains("Out of scope:\nthe installer.\n"), "{content}"); +} + +/// A campaign filed with no description holds the placeholder, and appending replaces it +/// rather than following it: the alternative reads `_No description provided._` above the +/// description. `append_section_body`'s rule, so nothing here handles the case. +#[test] +fn appending_to_an_empty_description_replaces_the_placeholder() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + run(&temp, &["campaign", "add", "--title", "No prose yet"]); + + let uuid = { + let names = campaigns(&worklane); + let name = names + .iter() + .find(|name| name.ends_with("_no-prose-yet.md")) + .expect("the campaign was not filed"); + name.split('_').next().unwrap().to_string() + }; + assert!( + campaign_file(&worklane, &uuid).contains("_No description provided._"), + "the placeholder is not what add writes any more" + ); + + let out = run( + &temp, + &[ + "campaign", + "append", + "No prose yet", + "-d", + "The first thing said.", + ], + ); + assert!(out.status.success(), "{}", stderr(&out)); + + let content = campaign_file(&worklane, &uuid); + assert!(content.contains("The first thing said."), "{content}"); + assert!( + !content.contains("_No description provided._"), + "the placeholder is still above the description: {content}" + ); +} + +/// Every value blank is refused rather than writing nothing quietly, the answer `append` +/// gives a ticket, in the same words: appending nothing was never a way to empty anything, +/// so there is no flag to name. +#[test] +fn an_all_blank_append_is_refused() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + let before = campaign_file(&worklane, CAMP_A); + + let out = run(&temp, &["campaign", "append", "v1 release", "-d", " "]); + + assert_eq!(out.status.code(), Some(1), "{}", stderr(&out)); + assert!(stderr(&out).contains("Nothing to append"), "{}", stderr(&out)); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "the file was written"); +} + +/// A bare `campaign append ` is a usage error rather than a silent no-op, the way +/// a bare `campaign set` is. `--description` is `required` rather than a group of one. +#[test] +fn campaign_append_with_no_description_is_a_usage_error() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + let before = campaign_file(&worklane, CAMP_A); + + let out = run(&temp, &["campaign", "append", "v1 release"]); + + assert_eq!(out.status.code(), Some(2), "{}", stderr(&out)); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written"); +} + +/// Appending to a scalar has no meaning, which is the line `append` already draws for a +/// ticket: no `--title` there and none here, and no `--codename` either. +#[test] +fn campaign_append_offers_only_the_description() { + let temp = TempDir::new().unwrap(); + setup_worklane(&temp); + + let out = run(&temp, &["campaign", "append", "--help"]); + let help = stdout(&out); + + assert!(help.contains("--description"), "{help}"); + assert!(!help.contains("--title"), "{help}"); + assert!(!help.contains("--codename"), "{help}"); + assert!(!help.contains("--force"), "{help}"); +} + +/// A campaign is addressed here by the same tiers everything else takes, codename included, +/// because it goes through `resolve_campaign` rather than a lookup of its own. +#[test] +fn campaign_append_resolves_the_campaign_by_its_codename() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + run(&temp, &["campaign", "set", "v1 release", "-c", "beaver"]); + + let out = run(&temp, &["campaign", "append", "beaver", "-d", "One more thing."]); + + assert!(out.status.success(), "{}", stderr(&out)); + assert!( + campaign_file(&worklane, CAMP_A).contains("One more thing."), + "{}", + campaign_file(&worklane, CAMP_A) + ); +} + +/// An unknown campaign leaves every campaign alone, the answer `campaign set` and `assign` +/// already give. +#[test] +fn campaign_append_refuses_an_unknown_campaign() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + let before = campaign_file(&worklane, CAMP_A); + + let out = run(&temp, &["campaign", "append", "nothing-by-that-name", "-d", "Text."]); + + assert_eq!(out.status.code(), Some(1), "{}", stderr(&out)); + assert!(stderr(&out).contains("No campaign found"), "{}", stderr(&out)); + assert_eq!(campaign_file(&worklane, CAMP_A), before, "something was written"); +} + +// ------------------------------------------------------ the shared machinery -- + +/// A campaign has one section where a ticket has four, and the section table in `util.rs` is +/// what both go through. So the surgery has to land against `## Metadata`, which is the only +/// heading that follows a campaign's description, and leave everything outside the body +/// alone: a handwritten section, the owner, and the codename in its place. +#[test] +fn the_description_is_edited_in_place_in_a_file_with_one_section() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + run(&temp, &["campaign", "set", "v1 release", "-c", "v1"]); + + let path = worklane + .join("campaigns") + .join(format!("{}_{}.md", CAMP_A, slug("v1 release"))); + let original = fs::read_to_string(&path).unwrap(); + fs::write( + &path, + original.replace("## Metadata", "## Notes\nA handwritten note.\n\n## Metadata"), + ) + .unwrap(); + + run(&temp, &["campaign", "set", "v1", "-d", "Replaced."]); + run(&temp, &["campaign", "append", "v1", "-d", "Added."]); + + let content = campaign_file(&worklane, CAMP_A); + assert!(content.contains("## Description\nReplaced.\n\nAdded.\n"), "{content}"); + // Nothing outside the body moved: the section that follows it, the handwritten one + // between them, and the fields under it. + assert!(content.contains("## Notes\nA handwritten note."), "{content}"); + assert!(content.contains("- **Codename**: v1"), "{content}"); + assert!(content.contains("- **Owner**: alice"), "{content}"); + assert!(!content.contains("**Status**"), "a status was invented: {content}"); + // And no section a campaign does not have was inserted to anchor against. + assert!(!content.contains("## Acceptance Criteria"), "{content}"); + assert!(!content.contains("## Implementation Plan"), "{content}"); +} + +/// The heading is the one in the section table, so `campaign set --description` reaches the +/// section `campaign_body` wrote and `campaign show` prints. A second spelling scoped to +/// campaigns is what this would catch. +#[test] +fn the_description_a_campaign_is_filed_with_is_the_one_set_replaces() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + run( + &temp, + &[ + "campaign", + "add", + "--title", + "Filed with prose", + "--description", + "As filed.", + ], + ); + run(&temp, &["campaign", "set", "Filed with prose", "-d", "As replaced."]); + + let out = run(&temp, &["campaign", "show", "Filed with prose"]); + let shown = stdout(&out); + assert!(shown.contains("As replaced."), "{shown}"); + assert!(!shown.contains("As filed."), "{shown}"); + // One Description heading in the file, not a second one written beside it. + let names = campaigns(&worklane); + let name = names + .iter() + .find(|name| name.ends_with("_filed-with-prose.md")) + .expect("not filed"); + let content = fs::read_to_string(worklane.join("campaigns").join(name)).unwrap(); + assert_eq!(content.matches("## Description").count(), 1, "{content}"); +} + +/// A campaign file with no Description heading is refused rather than given one back. Every +/// campaign the tool files carries the heading, so an insertion path here would be reachable +/// only from a hand-edited file, which is the opposite of the Relations case. The message +/// names the section and not the object, because both a ticket and a campaign reach it. +#[test] +fn a_campaign_with_no_description_section_is_refused() { + let temp = TempDir::new().unwrap(); + let worklane = board(&temp); + + let path = worklane + .join("campaigns") + .join(format!("{}_{}.md", CAMP_A, slug("v1 release"))); + let original = fs::read_to_string(&path).unwrap(); + fs::write( + &path, + original.replace("## Description\nWhat has to ship together.\n\n", ""), + ) + .unwrap(); + let before = fs::read_to_string(&path).unwrap(); + + for args in [ + ["campaign", "set", "v1 release", "-d", "Text."], + ["campaign", "append", "v1 release", "-d", "Text."], + ] { + let out = run(&temp, &args); + assert_eq!(out.status.code(), Some(1), "{}", stderr(&out)); + let said = stderr(&out); + assert!(said.contains("no description section"), "{said}"); + assert!(!said.contains("Ticket"), "a campaign was called a ticket: {said}"); + assert_eq!(fs::read_to_string(&path).unwrap(), before, "the file was written"); + } +}