Files
worklane/docs/completions.md
T
Ansho ReiandClaude Opus 5 634a1f44c4 (07ac4e1) Filter campaign ls by state, and lay its listing out as a table, and bump to 0.33.6
campaign ls printed every campaign and offered no way to narrow it, and the
row was assembled by hand, so a long title pushed the standing out of line
with the row above it and the created date the file already carries was not
shown at all.

--state takes open, done or empty and matches against Standing::state(),
so the derived value keeps one definition: a campaign reads [open] in the
listing if and only if --state open lists it. --state rather than --status,
which names one of the five ticket statuses everywhere else and would
invite --state backlog here. empty is the third value because an empty
campaign derives None deliberately, and a filter that could not reach those
would leave what has been filed and forgotten answerable only by reading
the whole listing. A filter that matches nothing names the value back,
since a silent listing reads as the other empty case.

The filter reaches --ids as well, the way ls --ids keeps its own, and is
the only thing that makes that path count members: an unfiltered completion
is as cheap as it was.

The columns are measured on the raw values and padded before anything is
painted, the rule metadata_cells follows. The codename is measured with the
title rather than given a column of its own: a campaign filed without one
spends nothing on it, so a column for it would be one most rows pad into
and some leave empty, and what a reader lines up is where a name ends and
its progress begins.

A flag's possible values now come off the command that holds the flag, so
campaign ls --state reaches ls's own arguments rather than campaign's. The
prompt offered nothing there while fish offered the three values, which
made a liar of the rule that a ValueEnum added anywhere is typeable on the
board the day it is added.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-15 16:42:21 +02:00

10 KiB

Shell Completions

The generated half, the fish half, and what keeps the two honest.

  • Two halves, and the split is the point. clap_complete generates the structure from the clap definition, so a new flag or subcommand is completed without anyone touching completions.rs. Only fish gets the second half, appended by fish_dynamic(), and it holds exactly what clap cannot know: the tickets on the board
  • The dynamic values come from worklane itself, as worklane ls --ids in a command substitution, one run per keypress at 2.5ms in release. So the completions are only as current as the binary on PATH: an older one without --ids completes nothing, which is a reinstall rather than a bug
  • What clap does and does not emit. It emits the possible values of an option, which is why mv --status <TAB> needs nothing here, and nothing for a positional, which is why the ls status and the completions shell are listed in the fish half. Both lists are read off the enums with possible_values, never written out, so a fifth status appears in the script on its own
  • Position is counted, not inferred. The four __worklane_* predicates all read $tokens[2] and the token count rather than using __fish_seen_subcommand_from, because campaign ls and campaign show are also an ls and a show that fish has seen, and because matching against the ticket list would run worklane again inside the condition. first_arg_of and second_arg_of count a top-level command's arguments, nested_arg_of matches a parent and a child so campaign show <TAB> can be told from chown alice <TAB>, which sit at the same token count, and command_is asks only which command this is, at any position in it
  • Every rule carrying -l needs a __worklane_command_is, and every_rule_naming_an_option_is_scoped_to_a_command is what enforces it. A bare complete -c worklane -l tag does not just complete that option's values, it tells fish the whole tool accepts --tag: worklane init --<TAB> offered six options that only relate and ls have. Fixed in 55ee6e3. __fish_seen_subcommand_from ls is not the scope to use, for the nesting reason above
  • The strongest completion check loads the script into fish and asks it for candidates. fish_offers_the_commands_the_statuses_and_the_values in tests/cmd_completions.rs sources the generated script into a throwaway shell standing in a real board, with this build's directory on the front of PATH, and compares complete -C against the ticket and the tag it put there. Every other test in the file reads the script as text, which cannot tell a rule that fires from one whose condition stopped matching, and that is how a completion actually breaks. Assert the values, not the flag names: clap emits every option's name on its own, so --tags and --blocked-by are offered with every hand-written rule deleted; what the dynamic half adds is what comes after the flag. Two traps, both paid for once: the shell must have fish_complete_path emptied, or complete -C autoloads ~/.config/fish/completions/worklane.fish and answers from whatever version wrote that, which is a guard that cannot fail; and the script is written beside the board rather than in it, since a rule that fires nothing falls back to listing the directory
  • fish --no-execute is the floor under that, not an oracle. It catches a script that does not parse, quotes still open at the end of the file or an unclosed block. Measured, not assumed: an apostrophe interpolated into a -d description partway down re-balances against the next quote and parses, corrupting every rule in between while the check passes; the same apostrophe in the last rule reaches the end unbalanced and is caught. Only fish gets this, because only fish gets a hand-written half
  • The rule counts in the completion tests are hardcoded on purpose. The walkers go clap → list and never see an entry naming something that does not exist, so a bogus pair in TAG_FLAGS is caught by every_tag_rule_takes_the_annotation_as_its_description counting one rule too many. Deriving that number from the lists it checks would grow with the bogus entry and pass. The seen totals in the walkers are hardcoded for the mirror reason, and both carry the note
  • The completion lists are kept honest by tests that walk the clap definition and fail on an argument left out of them. TICKET_COMMANDS and TICKET_SECOND_COMMANDS by position, TICKET_FLAGS, CAMPAIGN_COMMANDS, CAMPAIGN_NESTED_COMMANDS, CAMPAIGN_FLAGS and TAG_FLAGS likewise, the last against the test-local TAG_LIST_FLAGS and TAG_NEW_COMMANDS for the tag arguments that deliberately get no rule. The walk is one function, every_argument, since the tests differ only in the id they look for. Each also asserts how many it found, so a walker that stopped finding arguments fails rather than passing every assertion by never running them
  • A campaign is named in three shapes and a tag in one, which is why the lists are not one list: a campaign is assign's first positional, the first argument of campaign show and campaign set, and ls --campaign's value, and each needs a different fish rule. A tag is only ever an option value, and its values come from a different command
  • TICKET_FLAGS holds pairs, the command and the flag, and every ticket rule in the fish half is generated from it. Three commands carry a --clear and each takes something different: chown's names the ticket, since with no user to give there is no positional for it; relate's takes the kind and then the target; set's takes a field name clap already offers. So the command is half of the fact, and a list of bare flag names could only be scoped by hand, which is what the chown --clear rule used to be. every_ticket_flag_is_a_real_option walks each pair against the command it names, which a flat list could not do
  • The lists answer the board as well as the shell. argument_at reads every one of them to say what the argument at a given index of a typed line names — a ticket, a campaign, a tag, or a fixed list it takes off clap — which is what the command prompt completes against, see tui-prompts.md. Position is counted there exactly as it is counted here, so the two cannot come to disagree about mv --status done <ticket>; a second table on the board would be a copy the tests above never read. The values are the one half that is not shared: fish runs worklane ls --ids and the board reads the rows the tab already holds
  • TAG_FLAGS holds pairs where the others hold names, because the two options that take one tag are spelled differently: ls --tag filters on one and append --tags adds them, so a single rule naming both would tell fish that each command accepts the other's flag. One rule per pair, generated in fish_dynamic. add --tags and set --tags are in the test's TAG_LIST_FLAGS instead and get no rule: they take the whole list, so the token at the cursor is bug,tui and fish replaces a token entire, which would throw away what is already typed. The test walks both tag and tags, so the next one has to say which of the two it is
  • A ValueEnum is never listed twice, and argument_at is why the fish half's two hand-written value lists are the only ones. clap emits the possible values of an option, so mv --status and set --clear need nothing here and the board reads them off the same definition with Arg::get_possible_values. The ls status and the completions shell are positionals, which the fish generator emits nothing for, so those two are written into the block from the enums — and the board reaches them through get_positionals, which needs no Command::build the way get_index would
  • RELATION_KIND_FLAGS is the one position clap cannot answer for. relate --clear takes a kind and then a target, two values of different kinds under one flag, so possible values on it would refuse every target. Both renderers therefore say so themselves: the fish rule lists RelationKind::ALL and the table names the pair
  • ls --ids is the machine-readable listing, and one of the three outputs in the tree meant to be parsed: the short id, a tab, the title, unstyled. Two fields because fish reads what follows a tab as the description and a script reads cut -f1. It includes done, which the decorated listing leaves out, because a completion has to be able to name a finished ticket, and it skips a missing status directory rather than refusing, because an error printed over a shell prompt is worse than no candidates. The filters still apply, and an unknown --campaign is still refused
  • A flag's possible values are read off the command that holds the flag, nested or not. argument_at resolves the group's child when the second word names one, so campaign ls --state reaches ls's own arguments rather than campaign's, which carry no such flag. Without that the prompt offered nothing where fish offered the three values, and the promise that a ValueEnum added anywhere is typeable on the board the day it is added held only for a top-level command
  • campaign ls --ids is the same flag and the same two fields for the other object, and it deliberately skips the member counting the decorated listing does: members() reads every ticket on the board, and the caller here is a shell filling in candidates on a keypress. It also prints nothing on an empty board, where the decorated listing prints a sentence, because a sentence offered as a candidate is worse than no candidates
  • worklane tags is the third, and it is a command rather than a mode on ls. Two reasons: ls --tag <tag> answers what carries a tag and cannot answer what tags exist, which is the question a grooming sweep starts from, and a --tags beside a --tag is one letter from a filter that means something else. Alphabetical and case sensitive, matching the filter, so bug and Bug list separately and land next to each other, which is where a near-duplicate is spotted. Every status, done included: a tag that has fallen out of use is still part of what the vocabulary has been. assets/PLAN.md used to tell the agent to count tags with a show per ticket, and now points here