Fix completion git wrapper

[chris-peterson]

Closes #4

Context

git fi <TAB> offers filenames instead of branches and flags for a lot of people. git-fi ships completion, so this reads as broken rather than missing. The cause is that two different things named _git compete on the zsh function path and they dispatch subcommands differently: zsh's own _git calls _git-fi (hyphen), while the completion wrapper that ships with git — what Homebrew installs, and the common setup on macOS — calls _git_fi (underscore) under ksh emulation. git-fi ships a _git_fi, but it reads the command line from bash's COMP_WORDS, which git's zsh wrapper never sets, and it isn't on the fpath for zsh to autoload. Under that wrapper the completer generates nothing and zsh falls through to _files.

The fix reads the command line from git's portable $words/$cur so one _git_fi body serves both shells, and ships that body a second time as an fpath-autoloadable completions/_git_fi. Both come out of scripts/completion/git-fi.bash.tmpl, so they can't drift.

%%{ init: { 'look': 'handDrawn' } }%%
flowchart LR
    Tab["git fi TAB"] --> Which{"which _git is on fpath?"}
    Which -->|"zsh's own"| Dash["_git-fi"]
    Which -->|"git's wrapper"| Under["_git_fi"]
    Dash --> ZshFile["completions/_git-fi"]
    Under --> BashFile["completions/git-fi.bash in bash"]
    Under --> FpathFile["completions/_git_fi on the zsh fpath"]
    BashFile --> Shared["shared body from git-fi.bash.tmpl"]
    FpathFile --> Shared

Loading

A second, unrelated defect turned up while verifying the first, and is fixed here too: completions/_git-fi defines its completer but never calls it. zsh's autoload runs a completion file as the body of the function being autoloaded, so the first <TAB> in any shell executed the definitions and returned without completing — a silent beep, working only on the second tab. That one hits git-fi <TAB> and git fi <TAB> under zsh's built-in _git, and it is live on main today.

Review guide

Most to least critical.

• git-fi.bash.tmpl:42 — the actual bug. $words in place of COMP_WORDS; everything else about the branch follows from this line. The helpers moved inside _git_fi on the same pass, so the file is one function definition and zsh's autoload runs the body.
• git-fi.zsh.tmpl:62 — the second defect, one line. zsh's own _git ends the same way.
• gen-docs.ts:72-93 — one template body, two outputs, differing only in the header and the leading #autoload tag. The new file joins the outputs list, so npm run verify:generated covers it.
• cli.test.ts:97 — three assertions that pin the fixes: $words and not COMP_WORDS, the trailing _git-fi "$@", and byte-identical _git_fi bodies across the two generated files.
• quickstart.md:48 — install docs. Names both providers, tells you how to recognise which one you have (filename fallback), and covers both files.
• SPEC.md:66 — new CMP-02 for the two-provider requirement. The rest of the CMP block shifts up one to stay contiguous; STATUS.md follows.
• scripts/trial.sh — npm run trial:on / trial:off, for running the change against your real shell before publishing. Not in the package files.

completions/* and man/* are generated; read the templates and gen-docs.ts instead.

Validation

CI asserts on the contents of the generated files, which cannot tell you what a shell actually offers. So this was exercised against a real zsh 5.9 and git 2.55 driven through a pty, in a throwaway repo with feature-a (in fi), feature-b, feature-c on origin, reading the completion listing off the terminal.

All on the first <TAB>, both providers:

line	git's wrapper	zsh's built-in _git
git fi <TAB>	12 flags + help, install-completions	help, install-completions
git fi -<TAB>	12 flags	12 flags, with descriptions
git fi --add <TAB>	feature-b, feature-c	same
git fi --remove <TAB>	feature-a	same
git-fi <TAB>	help, install-completions	same

--add excludes the branch already in fi and --remove offers only it, which is the action-aware filtering working through $words under both dispatchers. No filename fallback anywhere. The one asymmetry is the command position: git's wrapper lists the flags there, while zsh's _arguments holds them until you type a -. The quickstart says so.