feat: Add zsh autocomplete with dynamic SSH host completion

[bagdevich]

🚀 Feature: Add zsh autocomplete with dynamic SSH host completion

Description

gitkey should support shell autocomplete to improve discoverability, speed up usage, and provide a more polished CLI experience.

The project already targets macOS and zsh, so the initial implementation should focus on zsh only.

Autocomplete should be implemented in-project, without relying on outdated third-party completion packages for Commander.

---

Goals

• Add autocomplete support for zsh
• Complete top-level gitkey commands
• Complete command-specific flags
• Complete SSH host aliases dynamically from ~/.ssh/config
• Integrate installation into the existing gitkey install-shell flow

---

Expected behavior

• gitkey <TAB> → suggests available commands

• gitkey open <TAB> → suggests SSH host aliases

• gitkey open --<TAB> → suggests relevant flags (--current, --pub, etc.)

• gitkey reveal <TAB> / gitkey show <TAB> → suggests SSH host aliases

• Commands that support it expose --current in completion

• gitkey install-shell installs both:

  • right prompt integration
  • zsh completion setup

---

Implementation approach

1. Internal completion command

Introduce a hidden command:

gitkey __complete ...

This command:

• receives current CLI context (argv)
• returns completion candidates (one per line)

Example:

gitkey __complete open

↓

vention
altabel
bagdevich

---

2. Zsh completion function

Create a zsh completion script that:

• hooks into compdef
• calls gitkey __complete
• maps output to _describe / _values

Example:

_gitkey() {
  local completions
  completions=("${(@f)$(gitkey __complete "$words[@]")}")
  _describe 'values' completions
}

compdef _gitkey gitkey

---

3. Dynamic SSH host completion

• Reuse existing SSH config parsing
• Return Host aliases dynamically
• Ensure completion reflects real-time state of ~/.ssh/config

---

4. Command/flag awareness

Completion logic should:

• understand current command (words[2])
• return only relevant flags for that command
• avoid suggesting invalid combinations

---

5. Shell installation

Extend:

gitkey install-shell

To:

• install prompt integration (existing)
• install zsh completion script
• update fpath if needed
• re-run compinit instructions

---

Suggested scope

• src/index.ts
• src/commands/complete.ts (new)
• src/shell/zshCompletion.ts (new)
• src/commands/installShell.ts (update)
• README.md (update)

---

Out of scope

• Bash completion
• Fish completion
• Windows shell completion

---

Acceptance criteria

• zsh users can install autocomplete via:

  gitkey install-shell

• Top-level commands complete correctly

• Relevant flags complete per command

• SSH host aliases are suggested dynamically

• Completion works with existing commands (open, use, reveal, show, etc.)

• Hidden internal command does not appear in gitkey --help

• README documents setup and usage

• No outdated completion dependencies are introduced

---

Nice to have

• Completion for common remote names (e.g. origin in use)
• Smarter context awareness (e.g. only show --current where applicable)
• Graceful fallback if ~/.ssh/config is missing

---

Why this matters

Autocomplete significantly improves CLI UX and makes gitkey feel like a production-grade developer tool.

This is a key step toward positioning gitkey as a full Git identity manager, not just a helper script.