Shell completion for fish, bash, zsh and PowerShell #44

New issue

Closed

opened 2026-10-22 23:44:49 -05:00 by jeff · 1 comment

jeff commented

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

Owner

Shell completion for fish, bash, zsh and PowerShell.

Decisions

zfj answers its own completion (docs/adr/0007-completion-is-answered-by-zfj.md). A hidden zfj __complete <words> is given every word after zfj, the last being the partial word (possibly empty). It answers one candidate to a line as value<TAB>description, already prefix-matched, and then a directive line: :files, :dirs or :none. Each shell's completion script only hands it the line and offers what comes back. A script reads a directive it doesn't know as :none, so the protocol can grow.
Never noisy: __complete writes nothing to stderr and always exits 0.
What is completed:
- Command words, group commands, options, and the values an option lists.
- Operation names for zfj op, and an operation's params.
- Local values: instance names, workflow files in the clone, files, directories.
- Nothing from the instance (numbers, labels, repositories, users), so no network and no token while completing.
Global options are offered only before the command, as ADR 0003 accepts them.
Descriptions come from command summaries, option notes and operation summaries. The bash script drops them.
zfj completion <fish|bash|zsh|powershell> prints the script. The scripts are plain files in src/cli/completions/, embedded with @embedFile, and installed as files without running zfj, since a cross build cannot run what it builds.
Testing: unit tests on __complete, and a flake check that loads each script in its real shell and completes zfj iss and zfj issue list --st.

Deferred

Completing values from the instance: issue, pull request and run numbers, labels, repositories, users.

Children

#45 __complete, zfj completion, fish
#46 bash
#47 zsh
#48 PowerShell
#49 local values
#50 packaging and README

Shell completion for fish, bash, zsh and PowerShell. ## Decisions - **zfj answers its own completion** (`docs/adr/0007-completion-is-answered-by-zfj.md`). A hidden `zfj __complete <words>` is given every word after `zfj`, the last being the partial word (possibly empty). It answers one candidate to a line as `value<TAB>description`, already prefix-matched, and then a directive line: `:files`, `:dirs` or `:none`. Each shell's **completion script** only hands it the line and offers what comes back. A script reads a directive it doesn't know as `:none`, so the protocol can grow. - **Never noisy:** `__complete` writes nothing to stderr and always exits 0. - **What is completed:** - Command words, group commands, options, and the values an option lists. - Operation names for `zfj op`, and an operation's params. - Local values: instance names, workflow files in the clone, files, directories. - Nothing from the instance (numbers, labels, repositories, users), so no network and no token while completing. - **Global options** are offered only before the command, as ADR 0003 accepts them. - **Descriptions** come from command summaries, option notes and operation summaries. The bash script drops them. - **`zfj completion <fish|bash|zsh|powershell>`** prints the script. The scripts are plain files in `src/cli/completions/`, embedded with `@embedFile`, and installed as files without running zfj, since a cross build cannot run what it builds. - **Testing:** unit tests on `__complete`, and a flake check that loads each script in its real shell and completes `zfj iss` and `zfj issue list --st`. ## Deferred Completing values from the instance: issue, pull request and run numbers, labels, repositories, users. ## Children - [ ] #45 `__complete`, `zfj completion`, fish - [ ] #46 bash - [ ] #47 zsh - [ ] #48 PowerShell - [ ] #49 local values - [ ] #50 packaging and README

jeff added the

ready-for-human

label

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

jeff referenced this issue

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

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

jeff referenced this issue

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

Complete in bash #46

jeff referenced this issue

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

Complete in zsh #47

jeff referenced this issue

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

Complete in PowerShell #48

jeff referenced this issue

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

Complete instances, workflow files, files and directories #49

jeff referenced this issue

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

Install the completion scripts with each package #50