7.9 KiB
7.9 KiB
The Command Line Surface
How arguments are defined and validated, and how the listing is filtered.
CLI Arguments
- The prose arguments carry
allow_hyphen_values, via thePROSEconstant incommand.rs:add --title,--description,--acceptance,--plan, and thecommentbody. Ticket text quotes flag names constantly, and without it a criterion reading--print is supportedis parsed as a flag and the whole ticket is refused with nothing written - The trade: on those five arguments a genuinely mistyped flag now lands as content rather than raising a usage error. That is the right way round for prose and the wrong way round for anything else, which is why
due,priority,tags,ownerandstatusare deliberately left without it. A mistyped flag there is still a usage error, exit 2, and no ticket is written. Do not addPROSEto a new argument unless it holds prose --dueis validated at parse time byiso_date, the way--priorityis bypriority_level. A date that is not real is a usage error, exit 2, with nothing written, which is the whole point of leaving the scalars withoutPROSE. One parser servesaddandset: the field has one definition of what it accepts, and validating onlyaddwould leavesetopen, which is the command a grooming sweep actually uses- The shape is checked before chrono is asked.
%Y-%m-%daccepts an unpadded2026-8-9, which would be stored exactly as typed and sort before2026-10-01in any string comparison. Checking the length and the two dashes first is what lets a valid date be stored unchanged instead of normalised on the way in, which is the difference between validating and rewriting - Strict on the way in, tolerant on the way out.
util::due_datestill cuts2026-12-31T09:30:00Zdown to its date. A file written before the parser existed, or by hand, can hold one and still has to render; refusing to display what is already stored would punish the reader for the writer's mistake - An empty
--duekeeps the clearing message rather than the date message. Somebody typing it is reaching for a way to clear the field, and the useful answer is the flag that does it campaign add --codenameis validated at parse time bycodename, which isnon_emptyplus one word. The board draws it as a label with a mark and no quoting, so~beaver releaseon that row reads as two labels and the second one is not a campaign; a title is where a sentence goes. Nothing else is checked: there is no registry of codenames, the same reasonls --tagrefuses to validate a tag, and a length limit would be a number invented in the parser when the row that draws it already drops a label it cannot hold- There are two empty-value parsers, and which one an argument takes is the point.
non_emptysays only that the value cannot be empty, for the arguments with no empty form: thelsfilters,relate's targets, andset --title, which addresses the ticket and names its file.clearablenames--clear, for the arguments whose field does have one:set --tags,--duethroughiso_date, and thechownuser. One message for both would either lie aboutls --tagor leave the useful half unsaid.add --duetakes the second one becauseiso_dateis shared, and the answer it points at is a command later rather than the omission that would do it now, which is close enough to be worth the shared parser.append --tagsis the one place the field has an empty form and the argument still takesnon_empty:appendhas no--clearof its own, so naming one would send the caller looking on this command for a flag that isset's - A status is a
util::Status, not a string.mv --statusand thelspositional take the value enum, so an unknown status is a usage error at parse time naming the four, exit 2, and no handler checks. That is the same bargain--dueand--prioritytake, and it is what lets the shells complete the four for free.Status::ALLis the flow order, whichstatus_dirs()andcmd_mvboth read rather than spelling the names again, andDONEis defined from it - The ticket positionals (
show <id>,mv <ticket>,comment <ticket>) are also left alone, so a search term starting with a hyphen is a usage error. Reachable now that a hyphen-leading title can be stored: use the UUID, or put the flags first and separate with--, as inmv --status committed -- -leading-title - A bare
--is a value when it follows an option (--title --stores--) and clap's end-of-options marker when it sits in a positional. So acommentbody of exactly--needs its own separator,comment <ticket> -- --. Without it the body is reported missing and nothing is written, which is a clear failure rather than a silent drop addhas no positionals, so anything after a bare--is an unexpected argument and fails- A paragraph break in a description is an empty
--descriptionvalue.cmd_addjoins the values with a single newline, so-d "First." -d "" -d "Second."writes the blank line.trim_blank_ends()drops blank values at either end, so a break never lands against a section heading, and an all-blank description reads as no description. Interior runs are kept verbatim rather than collapsed --acceptanceand--planare lists, one criterium or step per value, so a blank there is spacing rather than content and the opencode wrapper drops it. Only--descriptionpreserves blanks
Filtering the Listing
- The filters are one call,
filtered, becauselscollects a column in three places (a named status, the counts, and the grouped listing) and three call sites are three chances to apply a different set. Every filter is anOptionand none asked for keeps everything, which is what makes them compose in any combination without a rule per pair --tagmatches whole values, not the field.parse_tagshas already split the comma-separated field, so the filter compares against those trimmed values:--tag bugis not answered by a ticket taggedbugfix, and--tag "cli, filter"matches nothing, because the field as written is not itself a tag. A ticket with no tags matches none- Case sensitive, the opinion the field already takes:
tag_colordrawsBugandbugin two colours because they are two tags. A filter that folded them would list tickets carrying a tag nobody asked for, and would hide exactly the split a grooming sweep is looking for - One tag per invocation. Several would have to decide between and and or, and neither reading is obviously right for a board this size. That decision is its own ticket, along with a substring or regex match and a tag filter on the tui
- A tag nothing carries lists nothing rather than being refused, which is the opposite of
--campaign. A campaign is an object that either exists or does not, so it is resolved before anything is read and an unknown one is an error. A tag is free text with no registry: there is nothing to resolve against, and refusing an unknown one would mean maintaining a vocabulary the format deliberately does not have.assets/PLAN.mdtells the agent to check the spelling when a listing comes back empty, andworklane tagsis what it checks against, since that is the failure this trades for - An emptied status keeps the message
lsalready gives,No tickets in '<status>' status., rather than one per filter naming what excluded them. That is pre-existing behaviour for--priorityand--campaign, and one message for every filter is the consistent half of it. If it should name the filter, that is a change to what the CLI prints for three flags at once and belongs in its own ticket cmd_lstakes anLsArgs, which is what the boundary in the Rust Style rule came to: four filters, an output mode and the directory, two of them adjacentOption<String>values a caller could swap silently.--idswas the argument that tipped it, the wayaddbecameAddArgs. A new filter is a field there, not a parameter