[PR #250] [MERGED] feat(cli): complete template and snapshot names dynamically #291

New issue

Closed

opened 2026-10-29 14:21:52 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:21:52 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/250
Author: @NickNYU
Created: 9/6/2026
Status: ✅ Merged
Merged: 9/19/2026
Merged by: @LSX-s-Software

Base: main ← Head: feat/cli-template-snapshot-completion

📝 Commits (6)

d0b65ae Document the safe first slice of dynamic CLI completion
c4c462f feat(cli): complete template and snapshot names dynamically
d894b9a fix(cli): filter completion candidates by prefix before capping
a9465a7 chore(docs): drop the aenv completion design spec
a159a7f fix(cli): return partial snapshot pages and share build-status handling
e42dc2c fix(cli): stop snapshot pagination when a continuation token repeats

📊 Changes

6 files changed (+1026 additions, -34 deletions)

View changed files

📝 crates/aenv/src/client/snapshots.rs (+237 -11)
📝 crates/aenv/src/client/templates.rs (+17 -0)
📝 crates/aenv/src/commands/completion.rs (+734 -12)
📝 crates/aenv/src/commands/start.rs (+1 -0)
📝 crates/aenv/src/commands/template.rs (+15 -6)
📝 docs/src/getting-started/aenv-cli/shell-completion.md (+22 -5)

📄 Description

Follow-up to #163, which added dynamic sandbox-ID completion. This PR covers the remaining dynamic-completion slice of #37: template and snapshot names.

What it does

aenv start, aenv template watch, and aenv template delete now complete live resources from the existing list APIs — no new server API:

aenv start <TAB>                 # template and snapshot names, then IDs
aenv template watch <TAB>        # template names, then template IDs
aenv start --cold <TAB>          # nothing: the target is an OCI image reference

Names and aliases are offered ahead of IDs, since names are what users type and IDs are only a fallback for resources that have none. Candidate descriptions distinguish the kind and carry the underlying ID plus build status where available:

alpha         template 11111111-1111-1111-1111-111111111111 (ready)
alpha-old     template 11111111-1111-1111-1111-111111111111 (ready)
base          snapshot snap-1
snap-2        snapshot

Design notes

How --cold is detected. A candidate provider gets no context about the rest of the command line, but the completion callback runs as COMPLETE=<shell> aenv -- <words...>, so the words the user has typed are in our own argv. contains_cold_flag scans it and returns early — before credentials or the network are touched, so a cold start costs no API call at all. --cold is a boolean flag, so it can never be another argument's value here; --cold=true is matched too.

Candidate hygiene. Names and IDs are sorted within their groups so the order is stable across completion requests. Values are de-duplicated, since a template can list the same string as both a name and an alias, and two templates can share an alias. Each resource kind contributes at most 100 candidates — the budget is per kind so that a deployment with many templates cannot crowd snapshots out of aenv start's candidates.

Failure behavior is unchanged from #163: 500 ms connect / 1 s request timeouts, and silently no candidates when credentials, the server, or the network are unavailable. For aenv start, the template and snapshot lookups are independent — either one failing only costs that kind's candidates.

Two drive-by fixes

snapshot list --sandbox-id had no sandbox completion, although #37 lists it under the sandbox states table. It now completes running and paused sandboxes, like connect and delete.
The docs claimed sandbox candidates carry a template/state description, but the code attached no description at all. Sandbox candidates now carry template <id> (<state>), making the documented behavior real — sandbox IDs are UUIDs, so the description is the only thing distinguishing two candidates in the shell.

Docs

docs/src/getting-started/aenv-cli.md gains the template/snapshot completion examples and the --cold exception, and its sandbox-state table now includes snapshot list --sandbox-id.

Validation

cargo fmt -p aenv -- --check, cargo clippy -p aenv --all-targets -- -D warnings — both clean
26 completion tests pass (13 new): candidate ordering, help text, de-duplication, per-kind cap, --cold detection, and provider wiring asserted through the Command tree rather than generated script text
Verified against the real callback protocol by invoking the binary with the bash completer's env contract (_CLAP_COMPLETE_INDEX, _CLAP_IFS): with no credentials, completion is silent and exits 0, and static flag completion still works
Verified the live path against a local stub API, confirming the ordering and descriptions shown above

Unrelated pre-existing failure on macOS: commands::download::tests::preflight_merges_directories_and_requires_force_for_files fails with symbolic links are not supported: /var. It fails identically on a clean tree with these changes stashed, and this PR does not touch download.rs.

What remains on #37

Auto-installation of completion loaders (make install-aenv, scripts/install-cli.sh, scripts/install.sh, plus removal from make uninstall-aenv) — @rbalachandar's #115.

Open question

The 100-candidate-per-kind cap is my choice; #37 only says candidates should be limited and de-duplicated. Happy to change the number, or drop the cap, if you'd prefer.

🤖 Generated with Claude Code

_{🔄 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/250 **Author:** [@NickNYU](https://github.com/NickNYU) **Created:** 9/6/2026 **Status:** ✅ Merged **Merged:** 9/19/2026 **Merged by:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Base:** `main` ← **Head:** `feat/cli-template-snapshot-completion` --- ### 📝 Commits (6) - [`d0b65ae`](https://github.com/kvcache-ai/AgentENV/commit/d0b65aec735e6af76d2a72577014494c9fdf86da) Document the safe first slice of dynamic CLI completion - [`c4c462f`](https://github.com/kvcache-ai/AgentENV/commit/c4c462f5735fbd8b4ccc6fc80845b80a64626c68) feat(cli): complete template and snapshot names dynamically - [`d894b9a`](https://github.com/kvcache-ai/AgentENV/commit/d894b9ab582bcff21cab4b5aef852f0053df40fa) fix(cli): filter completion candidates by prefix before capping - [`a9465a7`](https://github.com/kvcache-ai/AgentENV/commit/a9465a7ca2cb6c3c102506be4e9bd13555d5c04d) chore(docs): drop the aenv completion design spec - [`a159a7f`](https://github.com/kvcache-ai/AgentENV/commit/a159a7f4a19302db96a2679cf91eb0b0d6a99b0c) fix(cli): return partial snapshot pages and share build-status handling - [`e42dc2c`](https://github.com/kvcache-ai/AgentENV/commit/e42dc2c98f2ac517ca9e5d518a28ec2851dfa35c) fix(cli): stop snapshot pagination when a continuation token repeats ### 📊 Changes **6 files changed** (+1026 additions, -34 deletions) <details> <summary>View changed files</summary> 📝 `crates/aenv/src/client/snapshots.rs` (+237 -11) 📝 `crates/aenv/src/client/templates.rs` (+17 -0) 📝 `crates/aenv/src/commands/completion.rs` (+734 -12) 📝 `crates/aenv/src/commands/start.rs` (+1 -0) 📝 `crates/aenv/src/commands/template.rs` (+15 -6) 📝 `docs/src/getting-started/aenv-cli/shell-completion.md` (+22 -5) </details> ### 📄 Description Follow-up to #163, which added dynamic sandbox-ID completion. This PR covers the remaining dynamic-completion slice of #37: template and snapshot names. ## What it does `aenv start`, `aenv template watch`, and `aenv template delete` now complete live resources from the existing list APIs — no new server API: ```bash aenv start <TAB> # template and snapshot names, then IDs aenv template watch <TAB> # template names, then template IDs aenv start --cold <TAB> # nothing: the target is an OCI image reference ``` Names and aliases are offered ahead of IDs, since names are what users type and IDs are only a fallback for resources that have none. Candidate descriptions distinguish the kind and carry the underlying ID plus build status where available: ``` alpha template 11111111-1111-1111-1111-111111111111 (ready) alpha-old template 11111111-1111-1111-1111-111111111111 (ready) base snapshot snap-1 snap-2 snapshot ``` ## Design notes **How `--cold` is detected.** A candidate provider gets no context about the rest of the command line, but the completion callback runs as `COMPLETE=<shell> aenv -- <words...>`, so the words the user has typed are in our own argv. `contains_cold_flag` scans it and returns early — before credentials or the network are touched, so a cold start costs no API call at all. `--cold` is a boolean flag, so it can never be another argument's value here; `--cold=true` is matched too. **Candidate hygiene.** Names and IDs are sorted within their groups so the order is stable across completion requests. Values are de-duplicated, since a template can list the same string as both a name and an alias, and two templates can share an alias. Each resource kind contributes at most 100 candidates — the budget is per kind so that a deployment with many templates cannot crowd snapshots out of `aenv start`'s candidates. **Failure behavior is unchanged from #163**: 500 ms connect / 1 s request timeouts, and silently no candidates when credentials, the server, or the network are unavailable. For `aenv start`, the template and snapshot lookups are independent — either one failing only costs that kind's candidates. ## Two drive-by fixes - `snapshot list --sandbox-id` had no sandbox completion, although #37 lists it under the sandbox states table. It now completes running and paused sandboxes, like `connect` and `delete`. - The docs claimed sandbox candidates carry a template/state description, but the code attached no description at all. Sandbox candidates now carry `template <id> (<state>)`, making the documented behavior real — sandbox IDs are UUIDs, so the description is the only thing distinguishing two candidates in the shell. ## Docs `docs/src/getting-started/aenv-cli.md` gains the template/snapshot completion examples and the `--cold` exception, and its sandbox-state table now includes `snapshot list --sandbox-id`. ## Validation - `cargo fmt -p aenv -- --check`, `cargo clippy -p aenv --all-targets -- -D warnings` — both clean - 26 completion tests pass (13 new): candidate ordering, help text, de-duplication, per-kind cap, `--cold` detection, and provider wiring asserted through the `Command` tree rather than generated script text - Verified against the real callback protocol by invoking the binary with the bash completer's env contract (`_CLAP_COMPLETE_INDEX`, `_CLAP_IFS`): with no credentials, completion is silent and exits 0, and static flag completion still works - Verified the live path against a local stub API, confirming the ordering and descriptions shown above Unrelated pre-existing failure on macOS: `commands::download::tests::preflight_merges_directories_and_requires_force_for_files` fails with `symbolic links are not supported: /var`. It fails identically on a clean tree with these changes stashed, and this PR does not touch `download.rs`. ## What remains on #37 Auto-installation of completion loaders (`make install-aenv`, `scripts/install-cli.sh`, `scripts/install.sh`, plus removal from `make uninstall-aenv`) — @rbalachandar's #115. ## Open question The 100-candidate-per-kind cap is my choice; #37 only says candidates should be limited and de-duplicated. Happy to change the number, or drop the cap, if you'd prefer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:21:52 +00:00