Complete the command line in fish, answered by zfj __complete #45

New issue

Closed

opened 2026-10-22 23:44:51 -05:00 by jeff · 0 comments

jeff commented

2026-10-22 23:44:51 -05:00

Owner

Part of #44

The completion engine, the zfj completion command, and the fish script. Glossary Completion script and ADR 0007 go in with this one.

zfj __complete <words…>, hidden from zfj --help, answers as ADR 0007 says.
The command line it understands:
- Global options before the command word (with --color's values), and the command words after them.
- A group's commands, and a command's options (long and short), with the values in a note's allowed list or an enum's tags (--state, --protocol, --color).
- A flag that takes a value completes that value, not more flags.
- Positional words take their place in order. Words after a rest -- get :files, since they belong to another program.
zfj op: operation names with their summaries, then that operation's params as --name flags.
Descriptions: the summaries and notes, first line only.
The data: read from the same tables --help reads (each group's commands, each Options struct's short, positional, rest and notes, the generated params), so there is no second copy to keep in step. The top-level commands in main.zig likely want a table with summaries, which zfj --help could then print from.
zfj completion fish prints src/cli/completions/zfj.fish, embedded. zfj completion with no shell, or an unknown one, is a usage error naming the four.
The fish script: calls zfj __complete with commandline -opc plus the current token, keeps descriptions, maps :files / :dirs to fish's file and directory completion, and treats an unknown directive as :none.
Tests:
- Unit tests of __complete: words in, candidates and directive out.
- A flake check (no VM) that loads the fish script in fish and completes zfj iss and zfj issue list --st.
- The other shells join that check as their scripts arrive.

Part of #44 The completion engine, the `zfj completion` command, and the fish script. Glossary **Completion script** and ADR 0007 go in with this one. - **`zfj __complete <words…>`**, hidden from `zfj --help`, answers as ADR 0007 says. - **The command line it understands:** - Global options before the command word (with `--color`'s values), and the command words after them. - A group's commands, and a command's options (long and short), with the values in a note's `allowed` list or an enum's tags (`--state`, `--protocol`, `--color`). - A flag that takes a value completes that value, not more flags. - Positional words take their place in order. Words after a `rest` `--` get `:files`, since they belong to another program. - **`zfj op`:** operation names with their summaries, then that operation's params as `--name` flags. - **Descriptions:** the summaries and notes, first line only. - **The data:** read from the same tables `--help` reads (each group's `commands`, each Options struct's `short`, `positional`, `rest` and `notes`, the generated params), so there is no second copy to keep in step. The top-level commands in `main.zig` likely want a table with summaries, which `zfj --help` could then print from. - **`zfj completion fish`** prints `src/cli/completions/zfj.fish`, embedded. `zfj completion` with no shell, or an unknown one, is a usage error naming the four. - **The fish script:** calls `zfj __complete` with `commandline -opc` plus the current token, keeps descriptions, maps `:files` / `:dirs` to fish's file and directory completion, and treats an unknown directive as `:none`. - **Tests:** - Unit tests of `__complete`: words in, candidates and directive out. - A flake check (no VM) that loads the fish script in fish and completes `zfj iss` and `zfj issue list --st`. - The other shells join that check as their scripts arrive.

jeff added the

ready-for-agent

label

2026-10-22 23:44:51 -05:00

jeff added a new dependency

2026-10-22 23:44:59 -05:00

#46 Complete in bash

jeff added a new dependency

2026-10-22 23:44:59 -05:00

#47 Complete in zsh

jeff added a new dependency

2026-10-22 23:45:00 -05:00