proposal: ~~help and~~ completion framework

[kyleburton]

This was originally envisioned as a help and completion framework using annotation style comments:

# @help.cmd:cmd|oneline help text
# @help.long:cmd|multi line
# @help.long:cmd|help descriptions

# @help.cmd:cmd:subcmd|oneline help text
# @help.long:cmd:subcmd|multi line
# @help.long:cmd:subcmd|help descriptions

# @completions:<<cmd>>:opts|<<options for --foo or --bar=qux style parameters>> i.e. not counted as positional
# @completions:<<cmd>>:2|local dev stage preprod prod
# @completions:<<cmd>>:3|<<options for position 3>
# @completions:<<cmd>>:4|<<options for position 4>   
# @completions:help:2!<<shell-function-to-gen-opts-for-position-2>                                                                        

# how might we support completion for sub-commands and options specific to sub commands?

While this is simpler for static completions, it is more complex for dynamic cases.

Instead we can have tasks define well named helper functions <task>:complete that is responsible for returning the set of completions. Completions can be performed by inspecting the number of arguments and the positional arguments, for example:

bake_task deploy "Deploy a service to an environment"
function deploy () {
  local env="$1" service="$2" version="$3"
  # ... deploy logic
}

function deploy:complete () {
  local cur="$1"
  shift
  # $# is now the count of already-typed arguments
  local arg_pos=$#

  case "$arg_pos" in
    0)
      echo "production staging dev"
      ;;
    1)
      local env="$1"
      case "$env" in
        production) echo "api worker frontend" ;;
        staging)    echo "api worker frontend debug-service" ;;
        dev)        echo "api worker frontend debug-service mock-service" ;;
        *)          echo "api worker frontend" ;;
      esac
      ;;
    2)
      # Pull versions dynamically from git tags
      git tag --list 'v*' 2>/dev/null
      ;;
  esac
}