feat(cli): codegraph completions for zsh/bash/fish/powershell with auto-detected install paths

[HelgeSverre]

Summary

Adds codegraph completions <shell> for zsh, bash, fish, and PowerShell. With --install, the command auto-detects the right location for the user's environment (oh-my-zsh, Homebrew, XDG, $PROFILE) and writes there — so the install is actually a one-shot, not "drop a file then go edit your dotfile" like every other CLI's completion installer.

codegraph completions zsh        --install   # → reports (detected: <tier>)
codegraph completions bash       --install
codegraph completions fish       --install
codegraph completions powershell --install

Without --install, the script goes to stdout — pipe it wherever you want.

Why

Every CLI that ships an --install for completions handles the path the same broken way: the docs tell you to redirect to ${fpath[1]}. On most systems ${fpath[1]} is /usr/local/share/zsh/site-functions or similar — root-owned. The "one-line install" silently requires sudo, or fails, or the user adds a custom dir to $fpath and remembers to do it again on every machine. gh, kubectl, helm, rustup, Jottacloud's docs — same brittle pattern.

This PR does detection properly. The priority order per shell:

Shell	Tier 1	Tier 2	Tier 3
zsh	oh-my-zsh ($ZSH/completions/)	<prefix>/share/zsh/site-functions/ if writable	~/.zsh/completions/ (prints fpath hint)
bash	<homebrew>/etc/bash_completion.d/ if writable	XDG ~/.local/share/bash-completion/completions/	—
fish	~/.config/fish/completions/	—	—
powershell	Standalone .ps1 in ~/.config/powershell/ (or ~/Documents/PowerShell/ on Windows) + idempotent dot-source line in $PROFILE	—	—

The installer reports (detected: <tier>) so the user can see which rule fired. Unknown shells (nushell, xonsh, etc.) exit non-zero with a hint, writes nothing.

What's in the PR

File	Purpose
src/completions/index.ts	Public API: emit(), parseShell(), installCompletions()
src/completions/introspect.ts	Walks commander's Command tree → plain CommandDesc (decouples emitters from commander internals)
src/completions/zsh.ts	_arguments / _values emitter
src/completions/bash.ts	compgen / complete -F emitter
src/completions/fish.ts	complete -c codegraph declarations
src/completions/powershell.ts	Register-ArgumentCompleter -Native static script (clap_complete pattern)
src/completions/install.ts	detectInstallTarget() per-shell tiers + idempotent $PROFILE append
src/bin/codegraph.ts	Registers .command('completions <shell>')
__tests__/completions.test.ts	39 structural + detection-tier + help/version regression assertions
docker/smoke-completions/*	End-to-end smoke harness (zsh/bash/fish/pwsh in a pinned container)
README.md	New ### codegraph completions section under CLI Reference

Zero new dependencies. Uses commander's existing introspection API (cmd.options, cmd.registeredArguments, cmd.commands, cmd.aliases()).

Design calls worth flagging

zsh is structural-tested, not content-tested

zsh has no complete -C equivalent. Full content testing would require _main_complete running under a real ZLE widget context with a properly-set $compstate / $state / $opt_args — which scripts cannot manufacture. I tried a compadd shim against _codegraph_commands (the simplest helper, which uses _values); it silently captured nothing because _values short-circuits on missing context. PTY + expect is the only path to full testing, and that's flaky across zsh 5.7/5.8/5.9 and across TERM / locale / zle configurations — too unreliable for CI.

What clap_complete, oclif, click, and Commander.js itself all ship for zsh: structural-only. This PR matches that bar. The smoke verifies:

• zsh -n parses the script
• compinit registers _codegraph as an autoloadable completion
• The file body executes far enough to define all per-subcommand helpers (_codegraph_init, _codegraph_query, etc.) — catches "script crashed mid-body"

If you want stronger zsh coverage in the future, the realistic path is zpty-based testing (what Fig uses) — but that's a separate engineering effort.

PowerShell follows the clap_complete static pattern

Not the cobra/gh pattern (which calls back into the binary at tab-press time via a hidden __complete subcommand). The clap_complete idiom is fully static: Register-ArgumentCompleter -Native, walk $commandAst.CommandElements into a semicolon-joined path string, switch on that string, emit [CompletionResult]::new(...) per candidate, filter by $wordToComplete.

The static pattern is testable non-interactively via TabExpansion2 — clean analog to fish's complete -C. Full content assertions for top-level subcommands, flags, and alias dispatch are in the smoke (docker/smoke-completions/test-powershell.sh).

--install for PowerShell modifies $PROFILE

Touching the user's $PROFILE is invasive. The reasoning for doing it anyway:

1. The user explicitly invoked --install — modifying things is the contract.
2. PowerShell has no completions directory at all; $PROFILE dot-source is the only standard load path.
3. The appended line is one self-explanatory comment + dot-source. Easy to find and remove.
4. Idempotent: a marker comment (# codegraph completions) is used to detect "already wired up" — re-running --install won't duplicate the line. Verified in the smoke harness.

Matches what oclif does. If you'd rather punt the $PROFILE edit to the user (write the .ps1 and tell them the line to add), I'm happy to change it.

Testing

# Unit tests (31 assertions, runs in <1s)
npx vitest run __tests__/completions.test.ts

# End-to-end smoke (Docker, opt-in — NOT wired into `npm test`)
npm run smoke:completions
# Expected final line: smoke: zsh bash fish powershell OK

The smoke harness:

• npm packs the artifact and npm install -gs it inside a pinned Node 22 + zsh + bash + fish + pwsh 7.6.1 container
• Tests against the actual published artifact, not the dev tree (catches packaging mistakes — wrong files: list, missing chmod, etc.)
• Covers full content for bash (COMPREPLY-driven), fish (complete -C), and PowerShell (TabExpansion2); structural for zsh
• Verifies oh-my-zsh tier-1 detection by creating a fake $ZSH dir mid-test
• Verifies PowerShell --install idempotency on re-run
• Verifies unsupported shells (nushell) exit non-zero with a clear message

The pwsh binary is pulled from PowerShell's GitHub releases (multi-arch tarball, pinned to 7.6.1) because Microsoft's Debian apt repo doesn't ship arm64. Image rebuilds in ~30 s cold, ~2 s warm. Adds ~250 MB to the image; not pushed anywhere, just used locally.

Isolation from the existing test suite

• npm test behavior is unchanged. The smoke is opt-in via npm run smoke:completions.
• vitest.config.ts untouched.
• Everything Docker-related lives under docker/ which is excluded from npm pack by the existing files: ["dist","scripts","README.md"] allowlist — nothing new ships to npm consumers.
• No new runtime or dev dependencies in package.json.

Verified

• npx tsc --noEmit clean
• npm run build succeeds
• npx vitest run __tests__/completions.test.ts → 39/39 pass
• npx vitest run → 681/682 pass (1 pre-existing watcher flake on Node 26; unrelated to this PR — git stash && vitest run __tests__/watcher.test.ts reproduces on master)
• npm run smoke:completions → exit 0
• Injection sanity test: deliberately remove complete -F _codegraph codegraph from the bash emitter, rebuild, rerun smoke → fails at the bash:registration assertion with exit 1. Restored.
• Interactive pwsh test on macOS (PowerShell 7.7-preview): caught two bugs missed by all prior structural tests — duplicate --version at root (commander's auto-registered Option colliding with a hardcoded one) and missing -h/--help on subcommands (commander hides helpOption from cmd.options). Both fixed in commit cb2389e via a single helpOption injection in the introspect layer; commit 45b8c3b adds 8 new vitest assertions + per-shell smoke assertions that explicitly count occurrences (would have caught both bugs). Demonstrates the smoke harness's value end-to-end — and exactly the kind of bug class structural tests miss.

Out of scope (deliberately)

• CI workflow — repo has no .github/workflows/. Adding one expands PR scope and is your call. The npm script is CI-ready when wanted.
• Windows-native smoke — the Docker container is Linux. Windows pwsh codepath (process.platform === 'win32' branch in detectInstallTarget) is covered by unit tests with mocked process, but not end-to-end. Adding a Windows container is possible but expensive.
• --uninstall — npm uninstall -g doesn't clean these files (and shouldn't — they survive the package removal and become inert). Easy follow-up if you want it.
• PowerShell $PROFILE confirmation prompt — see "Design calls" above.
• elvish / xonsh / nushell — only zsh/bash/fish/powershell are emitted. The other shells fail cleanly with "Unsupported shell" + the supported list. Drop in another emitter under src/completions/ if you want to add one later — the pattern is uniform.

Suggested CHANGELOG entry

### Added
- **Shell completions** (`codegraph completions <shell>`): generate Tab-completion
  scripts for zsh, bash, fish, and PowerShell (aliases: `pwsh`, `ps`). With
  `--install`, codegraph auto-detects the right location for the user's
  environment — oh-my-zsh's `$ZSH/completions/`, Homebrew's
  `share/zsh/site-functions/`, the XDG bash-completion path, fish's
  auto-discovered config dir, or PowerShell's `$PROFILE` (with idempotent
  dot-source line append). Unknown shells exit non-zero with a hint. The
  detected location is reported as `(detected: <tier>)` so users see which
  rule fired. Docker-based smoke harness (`npm run smoke:completions`)
  verifies the generated scripts work end-to-end in real shells.

Commits

This PR is 6 logically-distinct commits, reviewable in order:

1. feat(cli): add codegraph completions <shell> for zsh/bash/fish — the emitter foundation
2. test(completions): add docker-based end-to-end smoke test — the harness
3. feat(completions): auto-detect install target + add PowerShell support — the detection tiers + pwsh
4. docs(completions): expand README section with per-shell setup — usage docs
5. fix(completions): inject --help/-h once, drop duplicate --version — bug found via interactive pwsh testing on macOS; fixed at introspect layer
6. test(completions): regression coverage for --help/-h on subs and --version dedupe — vitest + smoke assertions that would have caught the bug

Happy to squash if you'd prefer a single commit on merge.