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) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-24 04:53:49 +02:00
co-authored by Claude Opus 5
parent 5dc087d49e
commit 3592584747
12 changed files with 652 additions and 56 deletions
+63 -16
View File
@@ -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 <c>` 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<String>,
/// Replace the description. Repeat the flag for more lines, empty for a paragraph break
///
/// The whole section, so a paragraph added to it is `campaign append --description`
/// rather than the description retyped
#[arg(short, long, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
/// Replace the codename, a single word to call the campaign by
///
/// The same parser `campaign add --codename` takes, so a codename is one thing however
@@ -449,6 +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 <c>` is therefore a usage error rather than a silent no-op.
///
/// No `--title` and no `--codename`, because appending to a scalar has no meaning. That is
/// the line `append` already draws for a ticket, where the title is absent for the same
/// reason.
#[derive(clap::Args)]
pub struct CampaignAppendArgs {
/// Campaign UUID, title, filename or codename
pub campaign: String,
/// Add a paragraph to the description. Repeat the flag for more lines within it
#[arg(short, long, required = true, allow_hyphen_values = PROSE)]
pub description: Vec<String>,
}
/// What a campaign holds: a title, a description and an owner.
///
/// Deliberately narrower than [`AddArgs`]. There are no acceptance criteria, because a
+14 -6
View File
@@ -50,11 +50,16 @@ pub const CAMPAIGN_COMMANDS: [&str; 1] = ["assign"];
/// Nested subcommands whose first argument is a campaign, as `parent child`.
///
/// `campaign show` and `campaign set`, and they are why the fish half needs a third
/// position helper: their argument is the *third* token, where `__worklane_first_arg_of`
/// reads the second and `__worklane_second_arg_of` counts a top-level command's arguments.
/// Neither can tell `campaign show <TAB>` from `chown alice <TAB>` by position.
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 2] = [("campaign", "show"), ("campaign", "set")];
/// `campaign show`, `campaign set` and `campaign append`, and they are why the fish half
/// needs a third position helper: their argument is the *third* token, where
/// `__worklane_first_arg_of` reads the second and `__worklane_second_arg_of` counts a
/// top-level command's arguments. Neither can tell `campaign show <TAB>` from
/// `chown alice <TAB>` by position.
pub const CAMPAIGN_NESTED_COMMANDS: [(&str, &str); 3] = [
("campaign", "show"),
("campaign", "set"),
("campaign", "append"),
];
/// Options whose value is a campaign.
pub const CAMPAIGN_FLAGS: [&str; 1] = ["campaign"];
@@ -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.
+89 -17
View File
@@ -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 <field>`, and a campaign's description has no cleared
/// form at all, per [`CampaignSetArgs`].
fn replaced_items(section: &Section, values: &[String], instead: &str) -> Result<Vec<String>> {
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"An empty value is a paragraph break, not a way to empty the {}: {}",
section.label,
instead
));
}
Ok(items)
}
/// The same for `append`, which has no way out to name: appending nothing was never a way
/// to empty anything, so the message says only that there was nothing to add.
fn appended_items(section: &Section, values: &[String]) -> Result<Vec<String>> {
let items = section.normalise(values);
if items.is_empty() {
return Err(anyhow!(
"Nothing to append to the {}: every value given was blank",
section.label
));
}
Ok(items)
}
/// Write the ticket back, renaming the file when a new title changes its slug.
///
/// The content goes down first and the rename second, the same order and for the same
@@ -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
+1
View File
@@ -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)
+8 -2
View File
@@ -1843,6 +1843,12 @@ pub fn clear_section_body(content: &str, section: &Section) -> Result<String> {
}
/// 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<String> {
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<String> = 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<String> {
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]