diff --git a/AGENTS.md b/AGENTS.md index bac7ec8..4869d8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -179,6 +179,7 @@ and this file is for what someone changing worklane's own code needs. - **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, `_.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 diff --git a/Cargo.lock b/Cargo.lock index e2add34..67a8fc8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1503,7 +1503,7 @@ dependencies = [ [[package]] name = "worklane" -version = "0.21.0" +version = "0.21.1" dependencies = [ "anyhow", "assert_cmd", diff --git a/Cargo.toml b/Cargo.toml index 5350ffa..5c12e0d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "worklane" -version = "0.21.0" +version = "0.21.1" edition = "2024" [dependencies] diff --git a/README.md b/README.md index 2930c4b..7f150cc 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ 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. 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, 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 ` | 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 8b00896..c6ec952 100644 --- a/assets/PLAN.md +++ b/assets/PLAN.md @@ -160,7 +160,7 @@ fields; a goal is a campaign. worklane campaign ls worklane campaign show v1 worklane campaign add --title "..." --codename v1 --description "..." -worklane campaign set v1 --codename beaver # or --title, on one already filed +worklane campaign set v1 --title "..." # or --codename, on one already filed worklane assign v1 1b78a24 ``` @@ -183,6 +183,9 @@ tui is usable on a narrow terminal" is a campaign. "The tui tickets" is a tag. 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. diff --git a/assets/SKILL.md b/assets/SKILL.md index 3f1e685..a399440 100644 --- a/assets/SKILL.md +++ b/assets/SKILL.md @@ -222,7 +222,9 @@ sentence, and it is the shortest thing that addresses the campaign at the comman Optional: a campaign without one is drawn and listed by its short id instead, which resolves but says nothing. `campaign set --codename ` gives one to a campaign that is already filed, which is what every campaign filed before the field -existed needs. +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 diff --git a/src/command.rs b/src/command.rs index 051c999..e5c62ff 100644 --- a/src/command.rs +++ b/src/command.rs @@ -337,6 +337,13 @@ pub enum CampaignCommand { /// 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 ` is a /// usage error rather than a silent no-op, exactly as it is for [`SetArgs`]. #[derive(clap::Args)] @@ -357,9 +364,19 @@ pub struct CampaignSetArgs { /// 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. + /// it was written. Replacing one a campaign already has needs `--force` #[arg(short, long, value_parser = codename)] pub codename: Option, + + /// 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. diff --git a/src/handlers.rs b/src/handlers.rs index db36b0f..c33d403 100644 --- a/src/handlers.rs +++ b/src/handlers.rs @@ -1242,13 +1242,38 @@ pub fn cmd_tags(worklane_dir: &Path) -> Result<()> { /// `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. +/// 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(); diff --git a/tests/cmd_campaign.rs b/tests/cmd_campaign.rs index 9a669c3..627712e 100644 --- a/tests/cmd_campaign.rs +++ b/tests/cmd_campaign.rs @@ -1113,3 +1113,120 @@ fn campaign_set_offers_no_description_and_no_owner() { 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")); +}