wso2 / wso2/wso2-cli

Set up tab completion for the user instead of printing the script at them

Open
#210 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ready-for-agent Type/Improvement
Dominant language
Go
Stars
0
Forks
3
Avg merge
8h 43m
Merged PRs (30d)
60

Description

Problem

Tab completion ships in v0.1.1 but nobody gets it without hand work:

  • install.sh / install.ps1 wire PATH and WSO2_HOME only. The installer, README, install page and docs never mention completion.
  • ws completion zsh typed in a terminal dumps ~200 lines of script. It reads as an error, and it does not say what to do with it.
  • The manual steps have traps: plain zsh needs compinit first, and ~/.oh-my-zsh/completions/ does not exist by default, so the redirect fails.

What to build

1. ws completion install [shell]

Detects the shell from $SHELL when none is named. Supports zsh, bash, fish, powershell.

  • zsh, bash: add source <(ws completion <shell>) inside the existing # >>> wso2 cli >>># <<< wso2 cli <<< profile block. Sourcing at start-up means the script never goes stale after a shell update.
  • fish: write ~/.config/fish/completions/ws.fish.
  • powershell: add ws completion powershell | Out-String | Invoke-Expression to $PROFILE.
  • Idempotent: a second run changes nothing and says so.
  • The command name comes from the build-time CLI name, not a literal ws.

Report, as a result (not raw prints):

Tab completion added for zsh.
Open a new terminal, then try: ws <TAB>
2. ws completion <shell> knows when it is on a terminal
  • stdout piped or redirected: print the script, exactly as today. source <(ws completion zsh) must keep working.
  • stdout is a TTY: print a short hint instead of the script, naming ws completion install, and --print to get the script anyway.
3. The installers set it up
  • install.sh and install.ps1 run ws completion install after installing the binary, and the summary says "Tab completion added for ."
  • WSO2_CLI_NO_PROFILE=1 skips it and prints the one manual line instead, the way it already does for PATH.
  • A failure to set up completion is a warning, never a failed install.
  • uninstall.sh already strips the profile block; it also has to remove the fish file. Same for uninstall.ps1.
4. Docs

A "Tab completion" section in the README and on the install page (scripts/site/index.html): the one command, and the per-shell manual line.

Where things are

  • internal/app/completion.go: what completion offers (namespaces, product commands, flags, context names). The completion command itself is Cobra's default; it needs replacing or wrapping to add install, --print and the TTY check.
  • scripts/install.sh: detect_profile, wire_path, remove_block, BLOCK_BEGIN / BLOCK_END, WSO2_CLI_NO_PROFILE (line ~400). scripts/uninstall.sh has the same block markers.
  • Tests to extend: internal/app/completion_test.go, test/acceptance/install_unix_test.go, install_windows_test.go, uninstall_unix_test.go, uninstall_windows_test.go.

Decisions already made

  • Profile line over a generated file for zsh and bash: never stale, costs ~20ms per new terminal.
  • Completion of installed products needs nothing regenerated: the script asks ws __complete at Tab time, so ws product install is picked up at once.
  • Piped output stays byte-for-byte what Cobra generates.

Open questions

  • zsh without compinit in the profile: should install add autoload -U compinit && compinit inside the block, or detect it and tell the user? Adding it is friendlier; oh-my-zsh users already have it, and running it twice is slow.
  • Should the profile edit live in Go (ws completion install) with the install scripts calling it, or stay in the scripts? One implementation in Go is preferred; confirm the scripts can rely on the freshly installed binary running on every supported platform.

Acceptance

  • Fresh install on zsh and bash: new terminal, ws <TAB> lists commands, no manual step.
  • ws completion zsh in a terminal prints the hint; ws completion zsh | head -1 prints #compdef ws.
  • ws completion install twice leaves one line in the profile.
  • Uninstall leaves no completion line or file behind.
  • WSO2_CLI_NO_PROFILE=1 leaves every profile untouched.

Found while

Testing the real v0.1.1 install on macOS, zsh with oh-my-zsh. source <(ws completion zsh) typed into one session did not persist, and the documented-nowhere redirect failed on a missing directory.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with internal/app/completion.go and completion_test.go, then trace profile handling in scripts/install.sh and scripts/uninstall.sh. Run the listed install and uninstall acceptance tests while covering the shell-specific behavior, idempotence, TTY output, profile opt-out, and cleanup described in the acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, powershell, shell
Domain
cli, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.