[PR #89] [MERGED] feat(cli): add shell completion scaffolding #172

New issue

Closed

opened 2026-10-29 14:20:37 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:37 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/89
Author: @rbalachandar
Created: 7/30/2026
Status: ✅ Merged
Merged: 8/6/2026
Merged by: @LSX-s-Software

Base: main ← Head: cli/shell-completion

📝 Commits (10+)

b4d6b81 feat(cli): add shell completion scaffolding
25562c4 fix(cli): harden completion output and tests
6a17694 Update crates/aenv/src/commands/completion.rs
81cb641 test(cli): validate completion features via Cli metadata
be16e95 test(cli): cover completion write branches and add error context
55124bd docs(cli): document shell completion
f8751d8 docs(cli): correct shell-completion install paths
d13bc78 feat(cli): install shell-completion loaders via the installers
205223d Update .github/workflows/ci.yml
08be532 Update .github/workflows/ci.yml

📊 Changes

8 files changed (+319 additions, -10 deletions)

View changed files

📝 Cargo.lock (+12 -2)
📝 crates/aenv/Cargo.toml (+1 -0)
➕ crates/aenv/src/commands/completion.rs (+229 -0)
📝 crates/aenv/src/commands/mod.rs (+1 -0)
📝 crates/aenv/src/commands/snapshot.rs (+1 -1)
📝 crates/aenv/src/commands/template.rs (+2 -2)
📝 crates/aenv/src/main.rs (+8 -5)
📝 docs/src/getting-started/aenv-cli.md (+65 -0)

📄 Description

Splits #37 into a static-first scaffolding change. This adds the aenv completion <shell> command and the static completion surface; dynamic resource completion and automatic installer integration are deferred to follow-up work.

What it does

aenv completion bash|zsh|fish emits a static completion script via clap_complete. The command tree is rebuilt from the Cli derive spec (crate::Cli::command()), so the generated script always reflects the real CLI. There is no separate completion definition to keep in sync.
Covers everything #37 lists under static completion: top-level and nested subcommands, command aliases, flags, the --output table|json enum, and local path arguments such as the Dockerfile passed to aenv build.
Documents manual installation into standard Bash, Zsh, and Fish completion directories, including the Zsh fpath guidance and one-session activation commands.
Elvish and PowerShell are intentionally excluded; #37 scopes the shells to Bash, Zsh, and Fish.

Behavior change worth calling out

The command aliases cn, ls, rm, snap, templates and the snapshot/template subcommand aliases use visible_alias. clap_complete emits only visible aliases, so this is required for alias completion to work. The visible side effect is that these aliases now also appear in --help. Runtime parsing is unchanged; the aliases were already accepted as input.

Dependency

Adds clap_complete = "4", matching the existing clap = "4" major.

Testing

cargo test -p aenv --bin aenv commands::completion — 11 completion tests covering Bash, Zsh, Fish, aliases, the --output enum, nested subcommands, and output/flush error handling.
cargo fmt --all -- --check passes.
cargo check -p aenv --bin aenv passes.

The workspace-wide make fmt / make clippy also build the server and storage crates, which require Linux and /dev/kvm, so only the aenv-scoped checks were run here. No integration tests apply to this CLI-only change.

Out of scope

Dynamic resource completion (sandbox IDs filtered by command-applicable state, template/snapshot names, and the aenv start --cold OCI-ref exception) and automatic completion installation/removal. The installer work will be handled separately using standard completion directories without modifying shell startup files.

Refs #37 - static scaffolding portion; dynamic completion and installer integration remain separate follow-up work.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/89 **Author:** [@rbalachandar](https://github.com/rbalachandar) **Created:** 7/30/2026 **Status:** ✅ Merged **Merged:** 8/6/2026 **Merged by:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Base:** `main` ← **Head:** `cli/shell-completion` --- ### 📝 Commits (10+) - [`b4d6b81`](https://github.com/kvcache-ai/AgentENV/commit/b4d6b8178ebf81c025112deca31db5d0bfce2601) feat(cli): add shell completion scaffolding - [`25562c4`](https://github.com/kvcache-ai/AgentENV/commit/25562c46c0b333ec44f9e6bf62a4f1431f204532) fix(cli): harden completion output and tests - [`6a17694`](https://github.com/kvcache-ai/AgentENV/commit/6a176943caa51c2856a0d98a2cff1b525eed91d1) Update crates/aenv/src/commands/completion.rs - [`81cb641`](https://github.com/kvcache-ai/AgentENV/commit/81cb641811b8b7b4b4125472a6a4564e0e3933b5) test(cli): validate completion features via Cli metadata - [`be16e95`](https://github.com/kvcache-ai/AgentENV/commit/be16e9592943a819a6db7a1eb543b876b6737412) test(cli): cover completion write branches and add error context - [`55124bd`](https://github.com/kvcache-ai/AgentENV/commit/55124bd229368261aad71a6c52c6a0bd0cbc5771) docs(cli): document shell completion - [`f8751d8`](https://github.com/kvcache-ai/AgentENV/commit/f8751d8c4642c8f2f0a5f494b56c53cb1ceefcb2) docs(cli): correct shell-completion install paths - [`d13bc78`](https://github.com/kvcache-ai/AgentENV/commit/d13bc787b7d7a32b7141705b587403c28f81f667) feat(cli): install shell-completion loaders via the installers - [`205223d`](https://github.com/kvcache-ai/AgentENV/commit/205223d5a2d21f2509f3e495f80853794176ec22) Update .github/workflows/ci.yml - [`08be532`](https://github.com/kvcache-ai/AgentENV/commit/08be532e49865bab8e8dc6d98f5dfa0a9332933b) Update .github/workflows/ci.yml ### 📊 Changes **8 files changed** (+319 additions, -10 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+12 -2) 📝 `crates/aenv/Cargo.toml` (+1 -0) ➕ `crates/aenv/src/commands/completion.rs` (+229 -0) 📝 `crates/aenv/src/commands/mod.rs` (+1 -0) 📝 `crates/aenv/src/commands/snapshot.rs` (+1 -1) 📝 `crates/aenv/src/commands/template.rs` (+2 -2) 📝 `crates/aenv/src/main.rs` (+8 -5) 📝 `docs/src/getting-started/aenv-cli.md` (+65 -0) </details> ### 📄 Description Splits #37 into a static-first scaffolding change. This adds the `aenv completion <shell>` command and the static completion surface; dynamic resource completion and automatic installer integration are deferred to follow-up work. ## What it does - `aenv completion bash|zsh|fish` emits a static completion script via `clap_complete`. The command tree is rebuilt from the `Cli` derive spec (`crate::Cli::command()`), so the generated script always reflects the real CLI. There is no separate completion definition to keep in sync. - Covers everything #37 lists under static completion: top-level and nested subcommands, command aliases, flags, the `--output table|json` enum, and local path arguments such as the Dockerfile passed to `aenv build`. - Documents manual installation into standard Bash, Zsh, and Fish completion directories, including the Zsh `fpath` guidance and one-session activation commands. - Elvish and PowerShell are intentionally excluded; #37 scopes the shells to Bash, Zsh, and Fish. ## Behavior change worth calling out The command aliases `cn`, `ls`, `rm`, `snap`, `templates` and the `snapshot`/`template` subcommand aliases use `visible_alias`. `clap_complete` emits only visible aliases, so this is required for alias completion to work. The visible side effect is that these aliases now also appear in `--help`. Runtime parsing is unchanged; the aliases were already accepted as input. ## Dependency Adds `clap_complete = "4"`, matching the existing `clap = "4"` major. ## Testing - `cargo test -p aenv --bin aenv commands::completion` — 11 completion tests covering Bash, Zsh, Fish, aliases, the `--output` enum, nested subcommands, and output/flush error handling. - `cargo fmt --all -- --check` passes. - `cargo check -p aenv --bin aenv` passes. The workspace-wide `make fmt` / `make clippy` also build the server and storage crates, which require Linux and `/dev/kvm`, so only the `aenv`-scoped checks were run here. No integration tests apply to this CLI-only change. ## Out of scope Dynamic resource completion (sandbox IDs filtered by command-applicable state, template/snapshot names, and the `aenv start --cold` OCI-ref exception) and automatic completion installation/removal. The installer work will be handled separately using standard completion directories without modifying shell startup files. Refs #37 - static scaffolding portion; dynamic completion and installer integration remain separate follow-up work. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:37 +00:00