mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-31 07:44:57 +08:00
Piotr Mlocek
1c5051209c
> **🏗️ build-from-issue-agent** Closes #71 ## Summary Add dynamic shell completion support using `clap_complete`'s `CompleteEnv`, plus a `navigator completions <shell>` subcommand (rustup-style) that outputs completion scripts to stdout with detailed per-shell setup instructions in `--help`. Completions are dynamic — the shell calls back into the `navigator` binary on each tab-press, so they are always in sync with the installed version. This also lays the groundwork for future runtime completers (e.g., listing sandbox names on tab, tracked in #83). ## Changes Made - `Cargo.toml`: Added `clap_complete = { version = "4.5", features = ["unstable-dynamic"] }` to workspace dependencies - `crates/navigator-cli/Cargo.toml`: Added `clap_complete` dependency - `crates/navigator-cli/src/main.rs`: - Added `CompleteEnv::with_factory(Cli::command).complete()` at the top of `main()` (before TLS/argument parsing) - Added `Completions { shell }` subcommand that re-invokes the binary with `COMPLETE=<shell>` and pipes the output - Added `CompletionShell` enum (bash, fish, zsh, powershell) - Added `COMPLETIONS_HELP` with per-shell setup instructions (similar to `rustup completions --help`) - Added 3 unit tests - `CONTRIBUTING.md`: Added shell completions section documenting `nav` wrapper setup ## Usage ```bash # Generate completions navigator completions fish > ~/.config/fish/completions/navigator.fish navigator completions bash > ~/.local/share/bash-completion/completions/navigator navigator completions zsh > ~/.zfunc/_navigator navigator completions powershell >> $PROFILE # See full per-shell instructions navigator completions --help # For the nav wrapper (rewrite registration target) navigator completions fish | sed 's/--command navigator/--command nav/' > ~/.config/fish/completions/nav.fish ``` ## Design Decision: Why stdout-only (no auto-install) We researched how 12 popular CLI tools handle completion installation: | Tool | Command | Writes files? | Modifies RC? | |------|---------|---------------|-------------| | gh, glab, kubectl, docker, rustup, mise, starship | `completion <shell>` | stdout only | No | | atuin | `gen-completions --shell <shell>` | stdout (`--out-dir` option) | No | | gcloud | `install.sh` | Yes | **Yes** | | Amazon Q | `q integrations install` | Yes | **Yes** | **10 of 12 tools** follow the same pattern: output to stdout, never modify RC files, explicit shell selection, clear `--help` instructions. Only gcloud and Amazon Q modify RC files (and both have been criticized for it). Our approach matches the industry consensus. ## Deviations from Plan - The original issue proposed a static `completions <shell>` subcommand using `clap_complete::generate()`. After discussion, we switched to dynamic `CompleteEnv` which is always up-to-date and enables future runtime completers. - Added a `navigator completions <shell>` subcommand (not in original plan) for discoverability — it wraps the `COMPLETE` env var mechanism with a familiar CLI UX. ## Tests Added - **Unit:** `cli_debug_assert` — validates CLI structure; `completions_engine_returns_candidates` — smoke test confirming the completion engine returns subcommand candidates; `completions_subcommand_appears_in_candidates` — verifies `completions` appears in tab-completion results - **Integration:** N/A - **E2E:** N/A ## Verification - [x] All tests passing - [x] Pre-commit checks passing (clippy warnings are pre-existing, not from this change) - [x] CONTRIBUTING.md updated with nav wrapper completion setup