Skip to content
SHC Docs

Completion module

Shell completion for shc is cobra-native:

  1. modules/completion/commands/completion.go — the generator: shc completion [bash|zsh|fish|powershell] dumps the shell script produced by cobra’s built-in generators (GenBashCompletionV2, GenZshCompletion, …) for the fully assembled command tree. --file PATH writes to an explicit path; --install writes to the shell’s conventional per-user location.
  2. cobra’s __complete dispatcher — the generated scripts call shc __complete <words>... on every TAB press. Cobra registers that hidden command itself during Execute and resolves candidates from the command tree (subcommands, flags, and any ValidArgsFunction hooks).

A legacy Python-contract shc __complete <type> command used to be registered by this module. Because cobra adds its dispatcher AFTER the registry graft and Find resolves to the first-added command, the legacy command shadowed cobra’s dispatcher and broke every generated script (shc __complete install "" → “accepts 1 arg(s), received 2”, zero candidates, no directive). It was removed; tests/unit/cli/cli_test.go’s TestBuild_CobraCompleteDispatcherNotShadowed guards against reintroduction.

Responsibilities

Section titled “Responsibilities”
  • Emit the four per-shell completion scripts by introspecting the assembled cobra root (wired in via completion.SetRoot from cmd/shc — no hard-coded command list).
  • Refuse unsupported shells with X400009INVSHL; surface filesystem failures on --file/--install as X500700FILWRT.
  • Provide completion.Service — the value-lookup catalog for dynamic candidates (tenants, stacks, environments, services, jobs, backups, apps, nodes, repos, plus the static enums scopes/outputs/runtimes/ roles). It queries /api/resource/<Type> best-effort: failures collapse to an empty list so the user’s shell never sees an error. Wiring it into per-flag ValidArgsFunction hooks is the intended successor for live value completion.

CLI surface

Section titled “CLI surface”
  • shc completion [bash|zsh|fish|powershell] [--file PATH] — print / write a completion script
  • shc completion <shell> --install — write to the shell’s convention path (see defaultInstallPath)
  • shc __complete ... — cobra’s hidden dispatcher; used by the emitted scripts

Service behaviour

Section titled “Service behaviour”
  • SHC_COMPLETION_TIMEOUT (ms, default 500) caps every lookup.
  • SHC_COMPLETION_DEBUG=<file> appends a timed record per lookup so operators can debug why a completion is empty or slow.
  • Saved context (tenant/stack/environment) falls back to SHC_TENANT/SHC_STACK/SHC_ENVIRONMENT, then the shc ctx active pointers.
Section titled “Related”