A tag declared with the wrong annotation was stuck with it, which is 32e98ab's hole arriving before the writer rather than after. The campaigns entry on this board was already in that state: it reserved the singular for the campaign command, and stopped being true the moment that tag was rolled in. `worklane tags set <tag> --annotation` replaces the whole annotation. `--annotation` is required, so a bare call is a usage error rather than a silent no-op, and an empty one writes the placeholder, which is why there is no `--clear`. `add` and `set` refuse what the other is for, each naming the other, so which one wrote a line is never a question of which was typed. No `--force`: a codename is guarded because a campaign is addressed by it, where an annotation is prose written to be revised. No rename: the tag is the key, so changing it means rewriting the Tags field of every ticket carrying it. `report` grew `report_in`, which takes the colour. `report` paints its subject green and green means title, so a tag could not reuse it: a tag is drawn in a `TAG_COLORS` slot or it is drawn wrong. Same wording, decision passed in, which is the trade `paint` makes with `color_text`. The no-op compares the rendered file rather than the annotation, the way `apply` compares content for a ticket field. `tags set` takes a tag the board already has, so it joins the new `TAG_NESTED_COMMANDS` and gets a fish rule offering `worklane tags`; `tags add` stays ruleless in `TAG_NEW_COMMANDS`. The guard now names both lists, so the next tag positional has to pick one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
837 lines
33 KiB
Rust
837 lines
33 KiB
Rust
use clap::Parser;
|
|
|
|
use std::sync::LazyLock;
|
|
|
|
use chrono::NaiveDate;
|
|
|
|
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
|
|
|
|
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
|
|
/// the same ramp the listing uses rather than spelled out a second time.
|
|
static PRIORITY_LEGEND: LazyLock<String> = LazyLock::new(priority_legend);
|
|
|
|
/// Reject a level outside the range at parse time, so no command has to.
|
|
fn priority_level(raw: &str) -> Result<u8, String> {
|
|
match raw.parse::<u8>() {
|
|
Ok(level) if PRIORITY_RANGE.contains(&level) => Ok(level),
|
|
_ => Err(format!(
|
|
"priority must be a whole number from {} to {}",
|
|
PRIORITY_RANGE.start(),
|
|
PRIORITY_RANGE.end()
|
|
)),
|
|
}
|
|
}
|
|
|
|
/// What `--version` prints: the crate version and the commit it was built from.
|
|
///
|
|
/// The sha is the part that matters. Two binaries built weeks apart both call
|
|
/// themselves 0.1.0, so without it there is no way to tell whether the copy on
|
|
/// PATH is the one carrying a given fix.
|
|
const VERSION: &str = concat!(env!("CARGO_PKG_VERSION"), " (", env!("WORKLANE_GIT_SHA"), ")");
|
|
|
|
#[derive(Parser)]
|
|
#[command(name = "worklane")]
|
|
#[command(about = "A CLI tool for managing project status")]
|
|
#[command(version = VERSION)]
|
|
#[command(propagate_version = true)]
|
|
pub struct Cli {
|
|
/// Absent opens the board view, the way a bare `frig` does.
|
|
#[command(subcommand)]
|
|
pub command: Option<Command>,
|
|
}
|
|
|
|
/// Reject an empty value at parse time, so it lands as a usage error rather than a
|
|
/// runtime one.
|
|
///
|
|
/// Two messages rather than one, because the arguments that use this fall into two
|
|
/// kinds. A search term or a title has no empty form at all, and that is all this says.
|
|
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
|
|
/// below: an accidentally empty variable must not blank a field silently, and somebody
|
|
/// typing an empty value on purpose is reaching for exactly the flag that does it.
|
|
///
|
|
/// Only the scalars use either one. For the multi-line sections an empty value is a
|
|
/// paragraph break.
|
|
fn non_empty(raw: &str) -> Result<String, String> {
|
|
if raw.trim().is_empty() {
|
|
return Err("value cannot be empty".to_string());
|
|
}
|
|
|
|
Ok(raw.to_string())
|
|
}
|
|
|
|
/// Reject an empty value on an argument whose field can be cleared, and say how.
|
|
///
|
|
/// The message names no command, because the arguments that use this belong to three:
|
|
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
|
|
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
|
|
/// flag, which is what the caller was reaching for anyway.
|
|
fn clearable(raw: &str) -> Result<String, String> {
|
|
if raw.trim().is_empty() {
|
|
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
|
|
}
|
|
|
|
Ok(raw.to_string())
|
|
}
|
|
|
|
/// Reject a due date that is not a real calendar date in the promised form.
|
|
///
|
|
/// At parse time, like `priority_level`, so a mistyped date is a usage error with
|
|
/// nothing written rather than a value the board goes on showing. `--due` is one of the
|
|
/// scalars deliberately left without `PROSE`, so this is the same bargain: nothing here
|
|
/// holds prose, and a wrong value should stop the command.
|
|
///
|
|
/// **The shape is checked before chrono sees it.** `%Y-%m-%d` accepts an unpadded
|
|
/// `2026-8-9`, which would then be stored exactly as typed and sort before `2026-10-01`
|
|
/// in any comparison of the strings. Checking the length and the two dashes first is
|
|
/// what lets a valid date be stored unchanged rather than normalised on the way in.
|
|
///
|
|
/// Strict on the way in, tolerant on the way out: `util::due_date` still cuts a
|
|
/// datetime down to its date, because a file written before this existed, or by hand,
|
|
/// can hold one and still has to render.
|
|
fn iso_date(raw: &str) -> Result<String, String> {
|
|
// An empty value keeps the message that explains why it is refused, since somebody
|
|
// typing it is reaching for a way to clear the field rather than mistyping a date.
|
|
clearable(raw)?;
|
|
|
|
let bytes = raw.as_bytes();
|
|
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
|
|
|
|
if !shaped || NaiveDate::parse_from_str(raw, "%Y-%m-%d").is_err() {
|
|
// Not echoing the value: clap has already printed `invalid value '...' for
|
|
// '--due <DUE>'` above this line, and `priority_level` says its piece the same
|
|
// way.
|
|
return Err(
|
|
"due date must be a real calendar date written as YYYY-MM-DD, for example 2026-08-29"
|
|
.to_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)
|
|
}
|
|
|
|
/// Reject a tag value that `ls --tag` could never match.
|
|
///
|
|
/// `--tag` matches a whole value of the comma-separated Tags field, so a value carrying a
|
|
/// comma is two tags and would be declared under a name nothing can be filtered by. A line
|
|
/// break is refused for the file's sake rather than the filter's: a tag is a heading in
|
|
/// `tags.md`, and a heading is one line.
|
|
///
|
|
/// Trimmed rather than refused for surrounding space, because `parse_tags` trims every
|
|
/// value it reads off a ticket and [`TagIndex::parse`] trims every heading it reads off the
|
|
/// vocabulary. Refusing here would refuse a value that both of those accept.
|
|
///
|
|
/// [`TagIndex::parse`]: crate::tag::TagIndex::parse
|
|
fn tag_value(raw: &str) -> Result<String, String> {
|
|
let value = raw.trim();
|
|
|
|
if value.is_empty() {
|
|
return Err("tag cannot be empty".to_string());
|
|
}
|
|
|
|
if value.contains(',') {
|
|
return Err(
|
|
"tag cannot contain a comma, which is what separates one tag from the next".to_string()
|
|
);
|
|
}
|
|
|
|
if value.contains(['\n', '\r']) {
|
|
return Err("tag must be a single line".to_string());
|
|
}
|
|
|
|
Ok(value.to_string())
|
|
}
|
|
|
|
/// Reject an annotation line that would be read back as a tag of its own.
|
|
///
|
|
/// The vocabulary is one heading per tag with its prose under it, so a line of prose
|
|
/// starting with the section marker would split the annotation and declare whatever
|
|
/// followed. Refused at parse time, where nothing has been written, rather than escaped on
|
|
/// the way in: an annotation is prose, and quietly rewriting prose is worse than asking for
|
|
/// a different line.
|
|
fn annotation_line(raw: &str) -> Result<String, String> {
|
|
match raw.lines().any(|line| line.starts_with(crate::tag::SECTION)) {
|
|
true => Err(format!(
|
|
"an annotation line cannot start with '{}', which is how the vocabulary file \
|
|
starts a tag",
|
|
crate::tag::SECTION
|
|
)),
|
|
false => Ok(raw.to_string()),
|
|
}
|
|
}
|
|
|
|
/// Arguments that carry prose, and therefore have to accept a value starting with
|
|
/// a hyphen.
|
|
///
|
|
/// Ticket text quotes flag names constantly, and without this a criterion reading
|
|
/// "--print is supported" is parsed as a flag and the whole ticket is refused. The
|
|
/// trade, spelled out in AGENTS.md: on these arguments a genuinely mistyped flag
|
|
/// now lands as content instead of raising a usage error. That is the right way
|
|
/// round for prose, and it is why `due`, `priority`, `tags`, `owner` and `status`
|
|
/// are deliberately left without it.
|
|
const PROSE: bool = true;
|
|
|
|
#[derive(clap::Subcommand)]
|
|
pub enum Command {
|
|
/// Initialize worklane in the current project
|
|
Init,
|
|
|
|
/// Add a new ticket to the backlog
|
|
Add(AddArgs),
|
|
|
|
/// List tickets, optionally filtered by status
|
|
#[command(after_help = PRIORITY_LEGEND.as_str())]
|
|
Ls(LsArgs),
|
|
|
|
/// Show a ticket by UUID or title
|
|
Show {
|
|
/// Ticket UUID or title to search for
|
|
id: String,
|
|
},
|
|
|
|
/// Move a ticket to a different status
|
|
Mv {
|
|
/// Ticket UUID or title
|
|
ticket: String,
|
|
|
|
/// Target status
|
|
#[arg(short, long)]
|
|
status: Status,
|
|
|
|
/// Force move (allows backward or non-sequential moves)
|
|
#[arg(short, long)]
|
|
force: bool,
|
|
},
|
|
|
|
/// Replace fields on an existing ticket
|
|
Set(SetArgs),
|
|
|
|
/// Add to a section of an existing ticket
|
|
Append(AppendArgs),
|
|
|
|
/// Record a relation from one ticket to another
|
|
Relate(RelateArgs),
|
|
|
|
/// Change the owner of a ticket, or return it to unset
|
|
///
|
|
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
|
|
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
|
|
/// association, so the argument order borrows it too.
|
|
///
|
|
/// A swap is caught by resolution rather than by a check of its own. Given
|
|
/// `chown 641e3d5 alice` the second argument has to resolve as a ticket, and a bare
|
|
/// username usually will not, so the call fails on its own. It is silently wrong
|
|
/// only when both arguments resolve, which needs a ticket whose title matches the
|
|
/// username.
|
|
Chown(ChownArgs),
|
|
|
|
/// Open the board view
|
|
Tui {
|
|
/// Projects to monitor, each resolved to the first `.worklane` at or above it.
|
|
/// Several are shown as tabs. Defaults to the working directory
|
|
paths: Vec<std::path::PathBuf>,
|
|
},
|
|
|
|
/// Tick acceptance criteria
|
|
Check(CheckArgs),
|
|
|
|
/// Untick acceptance criteria
|
|
Uncheck(CheckArgs),
|
|
|
|
/// Add a comment to a ticket
|
|
Comment {
|
|
/// Ticket UUID or title
|
|
ticket: String,
|
|
|
|
/// Comment body (required)
|
|
#[arg(allow_hyphen_values = PROSE)]
|
|
body: String,
|
|
|
|
/// Owner
|
|
#[arg(short, long)]
|
|
owner: Option<String>,
|
|
},
|
|
|
|
/// Group tickets that have to be finished together
|
|
Campaign {
|
|
#[command(subcommand)]
|
|
command: CampaignCommand,
|
|
},
|
|
|
|
/// Put a ticket in a campaign
|
|
///
|
|
/// Campaign first, ticket second, after `chown` and for the same reason: the
|
|
/// container is what the call is about, and the order is worth being consistent
|
|
/// about across the two commands that name two things.
|
|
///
|
|
/// The only writer of the Campaign field. `add` has no `--campaign` and `set` has
|
|
/// no `--campaign`, so the field keeps one writer the way Owner and Status do.
|
|
Assign {
|
|
/// Campaign UUID or title
|
|
campaign: String,
|
|
|
|
/// Ticket UUID or title
|
|
ticket: String,
|
|
},
|
|
|
|
/// The tag vocabulary: what the board carries, and what each tag means
|
|
///
|
|
/// 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 listing is machine-readable, like `ls --ids`: the tag, a tab, the count.
|
|
Tags {
|
|
#[command(subcommand)]
|
|
command: Option<TagCommand>,
|
|
},
|
|
|
|
/// Print a shell completion script
|
|
///
|
|
/// The structure comes from the clap definition, so a flag added here appears
|
|
/// without anyone remembering to. Fish gets a hand-written half appended for the
|
|
/// values only the board knows, see `completions.rs`.
|
|
Completions {
|
|
/// fish, bash, zsh, elvish or powershell
|
|
shell: clap_complete::Shell,
|
|
},
|
|
|
|
/// Install the agent skills that teach an agent to use worklane
|
|
///
|
|
/// Every shipped document by default. The optional name narrows it to one, and
|
|
/// `--print` requires it: a diff is against one document, and printing them all
|
|
/// concatenated would only look like one.
|
|
InstallSkill {
|
|
/// Skill to install or print, all of them if omitted
|
|
skill: Option<String>,
|
|
|
|
/// Overwrite an existing copy that has been modified
|
|
#[arg(long)]
|
|
force: bool,
|
|
|
|
/// Write it to stdout instead of installing it
|
|
#[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 `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 {
|
|
/// 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 {
|
|
/// Campaign UUID or title
|
|
campaign: String,
|
|
},
|
|
}
|
|
|
|
/// 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
|
|
/// campaign's definition of done is derived from its members rather than written down,
|
|
/// 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
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub title: String,
|
|
|
|
/// What the campaign is for. Use multiple flags for multiline descriptions
|
|
#[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>,
|
|
}
|
|
|
|
/// What the tag vocabulary can be asked for.
|
|
///
|
|
/// Optional, unlike [`CampaignCommand`], and that is the whole shape of the compatibility
|
|
/// here: `worklane tags` was the listing before it was a group, the shipped fish completion
|
|
/// calls it that way to fill in `ls --tag`, and a bare call turning into a usage error would
|
|
/// break a script for the sake of symmetry. So the bare form stays the listing, and `tags
|
|
/// ls` is the same thing spelled the way `campaign ls` is.
|
|
///
|
|
#[derive(clap::Subcommand)]
|
|
pub enum TagCommand {
|
|
/// Declare a tag, and what it means
|
|
Add(TagAddArgs),
|
|
|
|
/// Replace what a declared tag means
|
|
Set(TagSetArgs),
|
|
|
|
/// List the tags the board carries, and how many tickets carry each
|
|
Ls,
|
|
}
|
|
|
|
/// What declaring a tag takes: the tag, and what it is for.
|
|
///
|
|
/// No owner and no timestamp, which every other file under `.worklane/` carries. A tag is
|
|
/// not an object with a history, it is a word the board agrees on, and `git log` over
|
|
/// `tags.md` answers who wrote which line better than a field would.
|
|
#[derive(clap::Args)]
|
|
pub struct TagAddArgs {
|
|
/// The tag to declare, spelled the way `ls --tag` matches it
|
|
#[arg(value_parser = tag_value)]
|
|
pub tag: String,
|
|
|
|
/// What the tag means and when it is appropriate. Use multiple flags for multiline
|
|
/// annotations
|
|
#[arg(short, long, allow_hyphen_values = PROSE, value_parser = annotation_line)]
|
|
pub annotation: Vec<String>,
|
|
}
|
|
|
|
/// What can be replaced on a tag that is already declared: what it means, and nothing else.
|
|
///
|
|
/// No `--force`, unlike [`CampaignSetArgs`]. A codename is guarded because once a campaign
|
|
/// has one it is how the campaign is addressed, on every card and at every command line, so
|
|
/// replacing it silently breaks the way it is referred to. An annotation is prose written to
|
|
/// be revised and nothing addresses anything by it, so a guard would stand in front of the
|
|
/// command's whole purpose.
|
|
///
|
|
/// No rename. The tag *is* the key, so changing it means rewriting the Tags field of every
|
|
/// ticket carrying it. That is a migration, not a flag on `set`.
|
|
///
|
|
/// No `--clear`. An annotation is emptied with `--annotation ""`, which writes the same
|
|
/// placeholder a tag declared without one gets, so a second spelling would add nothing.
|
|
/// [`Clearable`] is a ticket's fields anyway, per [`SetArgs`].
|
|
///
|
|
/// `--annotation` is required, so a bare `worklane tags set <tag>` is a usage error rather
|
|
/// than a silent no-op, exactly as the group on [`CampaignSetArgs`] makes it for a campaign.
|
|
#[derive(clap::Args)]
|
|
pub struct TagSetArgs {
|
|
/// The tag to change, spelled the way it is declared
|
|
#[arg(value_parser = tag_value)]
|
|
pub tag: String,
|
|
|
|
/// What the tag means and when it is appropriate, replacing whatever it said before. Use
|
|
/// multiple flags for multiline annotations
|
|
#[arg(
|
|
short,
|
|
long,
|
|
required = true,
|
|
allow_hyphen_values = PROSE,
|
|
value_parser = annotation_line
|
|
)]
|
|
pub annotation: Vec<String>,
|
|
}
|
|
|
|
/// `ls` holds four filters, an output mode and nothing else, which is the boundary the
|
|
/// Rust Style rule in AGENTS.md names: two of the filters are adjacent `Option<String>`
|
|
/// values that a caller can swap silently, so the mode that joined them came as a
|
|
/// struct rather than a sixth parameter, the way `add` became [`AddArgs`].
|
|
#[derive(clap::Args)]
|
|
pub struct LsArgs {
|
|
/// Filter by status
|
|
pub status: Option<Status>,
|
|
|
|
/// Only show tickets at this priority, 1 (most urgent) to 5 (least)
|
|
#[arg(long, value_parser = priority_level)]
|
|
pub priority: Option<u8>,
|
|
|
|
/// Only show tickets carrying this tag, matched whole
|
|
#[arg(long, value_parser = non_empty)]
|
|
pub tag: Option<String>,
|
|
|
|
/// Only show the members of this campaign, by UUID or title
|
|
#[arg(long, value_parser = non_empty)]
|
|
pub campaign: Option<String>,
|
|
|
|
/// Print one ticket per line as its id and title, tab separated, for a script or a
|
|
/// completion. Done included, and the filters still apply
|
|
#[arg(long)]
|
|
pub ids: bool,
|
|
}
|
|
|
|
/// `add` carries every field a new ticket can hold, so it is a struct rather than an
|
|
/// inline variant: nine parameters at the call site is what `too_many_arguments` is
|
|
/// for, and `set`, `append` and `check` already pass their arguments this way.
|
|
///
|
|
/// No `ArgGroup`: `--title` is required on its own, and everything else is optional
|
|
/// because a ticket with only a title is a valid thing to file.
|
|
#[derive(clap::Args)]
|
|
pub struct AddArgs {
|
|
/// Ticket title
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub title: String,
|
|
|
|
/// Ticket description. Use multiple flags to create multiline descriptions.
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub description: Vec<String>,
|
|
|
|
/// Acceptance criteria. Accepts multiple flags, each will be interpreted as a single criterium
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub acceptance: Vec<String>,
|
|
|
|
/// Implementation plan. Accepts multiple flags, each will be interpreted as a single step
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub plan: Vec<String>,
|
|
|
|
/// Tags (comma-separated)
|
|
#[arg(short = 'g', long)]
|
|
pub tags: Vec<String>,
|
|
|
|
/// Due date (YYYY-MM-DD)
|
|
#[arg(long, value_parser = iso_date)]
|
|
pub due: Option<String>,
|
|
|
|
/// Owner
|
|
#[arg(short, long)]
|
|
pub owner: Option<String>,
|
|
|
|
/// Priority, 1 (most urgent) to 5 (least). Left unset if omitted.
|
|
#[arg(long, value_parser = priority_level)]
|
|
pub priority: Option<u8>,
|
|
}
|
|
|
|
/// `set` replaces a field outright. Owner is deliberately absent: `chown` owns that
|
|
/// field, and status is `mv`'s, so no field has two writers.
|
|
///
|
|
/// The group makes at least one field mandatory, so a bare `worklane set <ticket>` is
|
|
/// a usage error rather than a silent no-op.
|
|
#[derive(clap::Args)]
|
|
#[command(group(
|
|
clap::ArgGroup::new("set_fields")
|
|
.required(true)
|
|
.multiple(true)
|
|
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
|
|
))]
|
|
pub struct SetArgs {
|
|
/// Ticket UUID or title
|
|
pub ticket: String,
|
|
|
|
/// Replace the ticket title, renaming the file to match
|
|
#[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
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub description: Vec<String>,
|
|
|
|
/// Replace the acceptance criteria. Repeat the flag, one criterium per value
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub acceptance: Vec<String>,
|
|
|
|
/// Replace the implementation plan. Repeat the flag, one step per value
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub plan: Vec<String>,
|
|
|
|
/// Replace the tags
|
|
#[arg(short = 'g', long, value_parser = clearable)]
|
|
pub tags: Vec<String>,
|
|
|
|
/// Replace the due date (YYYY-MM-DD)
|
|
///
|
|
/// The same parser as `add`: one field, one definition of what a due date is. The
|
|
/// planning skill sets dates through `set` rather than `add`, so validating only
|
|
/// the one that files a ticket would leave the path that is actually used open.
|
|
#[arg(long, value_parser = iso_date)]
|
|
pub due: Option<String>,
|
|
|
|
/// Replace the priority, 1 (most urgent) to 5 (least)
|
|
#[arg(long, value_parser = priority_level)]
|
|
pub priority: Option<u8>,
|
|
|
|
/// Return a field to unset. Repeat the flag for more than one
|
|
///
|
|
/// The counterpart to the flag it names, and the only way to take a value away: an
|
|
/// empty value is a paragraph break for a section and a usage error for a scalar, so
|
|
/// neither can spell this. What goes back is what `add` writes for a field it was
|
|
/// never given.
|
|
///
|
|
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
|
|
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
|
|
#[arg(long, value_name = "FIELD")]
|
|
pub clear: Vec<Clearable>,
|
|
}
|
|
|
|
impl SetArgs {
|
|
/// A field this call both replaces and clears, if there is one.
|
|
///
|
|
/// clap cannot express the conflict, because `--clear` carries the field as a value
|
|
/// rather than in the flag's own name. So it is checked once here and refused, rather
|
|
/// than resolved by whichever of the two happens to be applied last, which is a
|
|
/// silent answer to a contradictory call.
|
|
pub fn contested(&self) -> Option<Clearable> {
|
|
self.clear.iter().copied().find(|field| match field {
|
|
Clearable::Due => self.due.is_some(),
|
|
Clearable::Tags => !self.tags.is_empty(),
|
|
Clearable::Priority => self.priority.is_some(),
|
|
Clearable::Description => !self.description.is_empty(),
|
|
Clearable::Acceptance => !self.acceptance.is_empty(),
|
|
Clearable::Plan => !self.plan.is_empty(),
|
|
})
|
|
}
|
|
}
|
|
|
|
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
|
|
/// that is what shapes the arguments.
|
|
///
|
|
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
|
|
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
|
|
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
|
|
/// can state outright. The typed call is the same either way; only who checks it differs.
|
|
///
|
|
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
|
|
/// both is a usage error from clap rather than a decision made here.
|
|
#[derive(clap::Args)]
|
|
pub struct ChownArgs {
|
|
/// New owner. Free text, like `add --owner`, checked against nothing
|
|
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
|
|
pub user: Option<String>,
|
|
|
|
/// Ticket UUID or title
|
|
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
|
|
pub ticket: Option<String>,
|
|
|
|
/// Return the owner to unset on this ticket, which is named here since there is no
|
|
/// user to name
|
|
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
|
|
pub clear: Option<String>,
|
|
}
|
|
|
|
impl ChownArgs {
|
|
/// The ticket the call names, and the owner to write on it, `None` being unset.
|
|
///
|
|
/// `None` for the pair is unreachable while the constraints above hold, and is an
|
|
/// error at the call site rather than a panic, so loosening one of them costs a
|
|
/// message instead of a crash.
|
|
pub fn target(&self) -> Option<(&str, Option<&str>)> {
|
|
match (self.clear.as_deref(), self.user.as_deref(), self.ticket.as_deref()) {
|
|
(Some(ticket), None, None) => Some((ticket, None)),
|
|
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
|
|
_ => None,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// `append` only offers the sections that hold multiple lines, since appending to a
|
|
/// scalar has no meaning.
|
|
#[derive(clap::Args)]
|
|
#[command(group(
|
|
clap::ArgGroup::new("append_fields")
|
|
.required(true)
|
|
.multiple(true)
|
|
.args(["description", "acceptance", "plan"])
|
|
))]
|
|
pub struct AppendArgs {
|
|
/// Ticket UUID or title
|
|
pub ticket: String,
|
|
|
|
/// Add a paragraph to the description. Repeat the flag for more lines within it
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub description: Vec<String>,
|
|
|
|
/// Add acceptance criteria. Repeat the flag, one criterium per value
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub acceptance: Vec<String>,
|
|
|
|
/// Add implementation plan steps, numbered on from the last. Repeat the flag
|
|
#[arg(short, long, allow_hyphen_values = PROSE)]
|
|
pub plan: Vec<String>,
|
|
}
|
|
|
|
/// `relate` is the only writer of the Relations section, the way `chown` is the only
|
|
/// writer of Owner. One flag per kind rather than a `--kind` value: the accepted kinds
|
|
/// are then clap's business, an unknown one is a usage error, and a call reads as a
|
|
/// sentence about the ticket it names.
|
|
///
|
|
/// Each flag repeats, so several relations of one kind land in a single call. The
|
|
/// targets are ticket searches, resolved by the same three tiers every other ticket
|
|
/// argument is, and stored as the target's uuid.
|
|
#[derive(clap::Args)]
|
|
#[command(group(
|
|
clap::ArgGroup::new("relation_kinds")
|
|
.required(true)
|
|
.multiple(true)
|
|
.args(["blocked_by", "regression_of", "relates_to"])
|
|
))]
|
|
pub struct RelateArgs {
|
|
/// Ticket UUID or title
|
|
pub ticket: String,
|
|
|
|
/// Ticket this one waits on. Its own moves are refused until the target is done
|
|
#[arg(long, value_parser = non_empty)]
|
|
pub blocked_by: Vec<String>,
|
|
|
|
/// Ticket whose fix this one broke
|
|
#[arg(long, value_parser = non_empty)]
|
|
pub regression_of: Vec<String>,
|
|
|
|
/// Ticket this one is merely related to. Symmetric, so it is recorded once
|
|
#[arg(long, value_parser = non_empty)]
|
|
pub relates_to: Vec<String>,
|
|
}
|
|
|
|
impl RelateArgs {
|
|
/// The relations asked for, one entry per kind, so the handler walks a table
|
|
/// instead of repeating itself three times.
|
|
pub fn requested(&self) -> [(RelationKind, &[String]); 3] {
|
|
[
|
|
(RelationKind::BlockedBy, &self.blocked_by),
|
|
(RelationKind::RegressionOf, &self.regression_of),
|
|
(RelationKind::RelatesTo, &self.relates_to),
|
|
]
|
|
}
|
|
}
|
|
|
|
/// `check` and `uncheck` are separate commands rather than one verb with a flag,
|
|
/// because the two read as opposites at the call site and neither needs the other's
|
|
/// name to make sense.
|
|
///
|
|
/// The criteria are optional: without any the criteria are listed and the index asked
|
|
/// for, or, where there is no terminal to ask at, returned as an error carrying the
|
|
/// same list.
|
|
///
|
|
/// Several terms in one call because finishing a ticket means ticking every box, and
|
|
/// one invocation per box resolved the ticket and rewrote the file each time. The
|
|
/// terms are variadic rather than a repeated flag: they address something that is
|
|
/// already there, the way the ticket positional does, instead of carrying content the
|
|
/// way `--acceptance` does.
|
|
#[derive(clap::Args)]
|
|
pub struct CheckArgs {
|
|
/// Ticket UUID or title
|
|
pub ticket: String,
|
|
|
|
/// Criterion indexes as shown by `show`, substrings of their text, or `all`. Prompts if omitted
|
|
pub criteria: Vec<String>,
|
|
}
|