From c95509ebfdbcc3c497f12697cfd2717bcb0a528b Mon Sep 17 00:00:00 2001
From: Igor Aleksandrov <igor.alexandrov@gmail.com>
Date: Thu, 15 May 2025 01:48:50 +0400
Subject: [PATCH] feat(kamal): add autocomplete support and aliases for Kamal
 (https://kamal-deploy.org/) (#13080)

---
 plugins/kamal/README.md        |  16 +
 plugins/kamal/_kamal           | 691 +++++++++++++++++++++++++++++++++
 plugins/kamal/kamal.plugin.zsh |  25 ++
 3 files changed, 732 insertions(+)
 create mode 100644 plugins/kamal/README.md
 create mode 100644 plugins/kamal/_kamal
 create mode 100644 plugins/kamal/kamal.plugin.zsh

diff --git a/plugins/kamal/README.md b/plugins/kamal/README.md
new file mode 100644
index 000000000..af5716826
--- /dev/null
+++ b/plugins/kamal/README.md
@@ -0,0 +1,16 @@
+# Kamal
+
+This plugin provides completion for [Kamal](https://kamal-deploy.org/) as well as some
+aliases for frequent Kamal commands.
+
+To use it, add kamal to the plugins array of your zshrc file:
+
+```zsh
+plugins=(... kamal)
+```
+
+## Aliase
+
+| Alias     | Command                          | Description                                                                      |
+|-----------|----------------------------------|----------------------------------------------------------------------------------|
+| kad       | `kamal deploy`                   | Deploy app to servers                                                            |
diff --git a/plugins/kamal/_kamal b/plugins/kamal/_kamal
new file mode 100644
index 000000000..52b29e814
--- /dev/null
+++ b/plugins/kamal/_kamal
@@ -0,0 +1,691 @@
+#compdef kamal
+
+# Description
+# -----------
+#  zsh completion for Kamal (https://kamal-deploy.org/)
+# -------------------------------------------------------------------------
+# Authors
+# -------
+#  * Igor Aleksandrov <igor.alexandrov@gmail.com>
+# -------------------------------------------------------------------------
+# Inspiration
+# -----------
+#  * docker-compose ohmyzsh completion script by @sdurrheimer Steve Durrheimer
+# -------------------------------------------------------------------------
+
+# _kamal_commands() {
+#   # Only initialize if empty
+#   if (( ${#kamal_commands} == 0 )); then
+#     kamal_commands=(
+#       accessory
+#       app
+#       audit
+#       build
+#       config
+#       deploy
+#       details
+#       docs
+#       help
+#       init
+#       lock
+#       proxy
+#       prune
+#       redeploy
+#       registry
+#       remove
+#       rollback
+#       secrets
+#       server
+#       setup
+#       upgrade
+#       version
+#     )
+#   fi
+
+#   _values 'Kamal commands' $kamal_commands
+# }
+
+typeset -gr _kamal_commands=(
+  'accessory:Control accessory services'
+  'app:Control application deployment'
+  'audit:Audit security of deployment'
+  'build:Build and manage app images'
+  'config:Show effective configuration'
+  'deploy:Deploy app to servers'
+  'details:Show details about deployment'
+  'docs:Open documentation in browser'
+  'help:Show command help'
+  'init:Initialize new Kamal project'
+  'lock:Manage deployment locks'
+  'proxy:Control reverse proxy'
+  'prune:Clean up containers and images'
+  'redeploy:Redeploy current version'
+  'registry:Manage Docker registry access'
+  'remove:Remove app from servers'
+  'rollback:Rollback to a previous version'
+  'secrets:Manage deployment secrets'
+  'server:Control server configuration'
+  'setup:Setup initial deployment'
+  'upgrade:Upgrade deployment'
+  'version:Show Kamal version'
+)
+
+# Helper function to display messages
+_kamal_message() {
+  local msg="$1"
+  _kamal_message "==> $msg"
+}
+
+# Helper function to extract destination names from ./config/deploy.*.yml
+_kamal_destinations() {
+  local -a dests
+  local file
+
+  # Check if config directory exists
+  if [[ ! -d "config" ]]; then
+    _kamal_message "Cannot find Kamal configuration directory at ./config" && return 1
+  fi
+
+  for file in config/deploy.*.yml(N); do
+    [[ $file =~ config/deploy\.(.+)\.yml ]] && dests+=("${match[1]}")
+  done
+
+  _values 'Destination' $dests
+}
+
+# Define global _kamal_flags array
+typeset -ga _kamal_flags
+_kamal_flags=(
+  '(-v --verbose )'{-v,--verbose}'[Detailed logging]'
+  '(--no-verbose --skip-verbose)'{--no-verbose,--skip-verbose}'[No detailed logging]'
+  '(-q --quiet --no-quiet --skip-quiet)'{-q,--quiet}'[Minimal logging]'
+  '(-q --quiet --no-quiet --skip-quiet)'{--no-quiet,--skip-quiet}'[No minimal logging]'
+  '--version=[Run commands against a specific app version]:version'
+  '(-p --primary --no-primary --skip-primary)'{-p,--primary}'[Run commands only on primary host instead of all]'
+  '(-p --primary --no-primary --skip-primary)'{--no-primary,--skip-primary}'[Do not run commands only on primary host]'
+  '(-h --hosts)'{-h,--hosts=}'[Run commands on these hosts instead of all]:hosts'
+  '(-r --roles)'{-r,--roles=}'[Run commands on these roles instead of all]:roles'
+  '(-c --config-file)'{-c,--config-file=}'[Path to config file]:config file:_files'
+  '(-d --destination)'{-d,--destination=}'[Specify destination to be used for config file]:destination:_kamal_destinations'
+  '(-H --skip-hooks)'{-H,--skip-hooks}'[Do not run hooks]'
+)
+
+_kamal() {
+  local context state state_descr line curcontext="$curcontext"
+  typeset -A opt_args
+
+  local ret=1
+
+  _arguments -C \
+    $_kamal_flags \
+    '1: :->command' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (command)
+      # First argument - show available commands
+      _describe -t kamal-commands "Kamal commands" _kamal_commands && ret=0
+      ;;
+    (args)
+      # Subsequent arguments - handle based on the command
+      case $words[1] in
+        (accessory)
+          _kamal_accessory && ret=0
+          ;;
+        (app)
+          _kamal_app && ret=0
+          ;;
+        (audit)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (build)
+          _kamal_build && ret=0
+          ;;
+        (config)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (deploy)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (details)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (docs)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (help)
+          _kamal_help && ret=0
+          ;;
+        (init)
+          local -a init_flags
+          init_flags=(
+            $_kamal_flags
+            '(--bundle --no-bundle --skip-bundle)--bundle[Add Kamal to the Gemfile and create a bin/kamal binstub]'
+            '(--bundle --no-bundle --skip-bundle)--no-bundle[Do not add Kamal to the Gemfile and create a bin/kamal binstub]'
+            '(--bundle --no-bundle --skip-bundle)--skip-bundle[Skip add Kamal to the Gemfile and create a bin/kamal binstub]'
+          )
+          _arguments $init_flags && ret=0
+          ;;
+        (lock)
+          _kamal_lock && ret=0
+          ;;
+        (proxy)
+          _kamal_proxy && ret=0
+          ;;
+        (prune)
+          _kamal_prune && ret=0
+          ;;
+        (redeploy)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (registry)
+          _kamal_registry && ret=0
+          ;;
+        (remove)
+          local -a remove_flags
+          remove_flags=(
+            $_kamal_flags
+            '(-y --confirmed --no-confirmed --skip-confirmed)'{-y,--confirmed}'[Proceed without confirmation question]'
+            '(-y --confirmed --no-confirmed --skip-confirmed)--no-confirmed[Proceed without confirmation question]'
+            '(-y --confirmed --no-confirmed --skip-confirmed)--skip-confirmed[Proceed without confirmation question]'
+          )
+          _arguments $remove_flags && ret=0
+          ;;
+        (rollback)
+          if (( CURRENT == 2 )); then
+            _kamal_message "Enter the version to rollback to" && ret=0
+          else
+            _values $_kamal_flags && ret=0
+          fi
+          ;;
+        (secrets)
+          _kamal_secrets && ret=0
+          ;;
+        (server)
+          _kamal_server && ret=0
+          ;;
+        (setup)
+          local -a setup_flags
+          setup_flags=(
+            $_kamal_flags
+            '(-P --skip-push)'{-P,--skip-push}'[Skip image build and push]'
+          )
+          _arguments $setup_flags && ret=0
+          ;;
+        (upgrade)
+          local -a upgrade_flags
+          upgrade_flags=(
+            $_kamal_flags
+            '(-y --confirmed --no-confirmed --skip-confirmed)'{-y,--confirmed}'[Proceed without confirmation question]'
+            '(-y --confirmed --no-confirmed --skip-confirmed)--no-confirmed[Do not proceed without confirmation question]'
+            '(-y --confirmed --no-confirmed --skip-confirmed)--skip-confirmed[Skip confirmation question]'
+            '(--rolling --no-rolling --skip-rolling)--rolling[Upgrade one host at a time]'
+            '(--rolling --no-rolling --skip-rolling)--no-rolling[Do not upgrade one host at a time]'
+            '(--rolling --no-rolling --skip-rolling)--skip-rolling[Skip rolling upgrade]'
+          )
+          _arguments $upgrade_flags && ret=0
+          ;;
+        (version)
+          _arguments $_kamal_flags && ret=0
+      esac
+    ;;
+  esac
+
+  return ret
+}
+
+_kamal_accessory() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  # Define accessory subcommands
+  local -a accessory_subcommands
+  accessory_subcommands=(
+    "boot:Boot new accessory service on host (use NAME=all to boot all accessories)"
+    "details:Show details about accessory on host (use NAME=all to show all accessories)"
+    "exec:Execute a custom command on servers within the accessory container (use --help to show options)"
+    "help:Describe subcommands or one specific subcommand"
+    "logs:Show log lines from accessory on host (use --help to show options)"
+    "reboot:Reboot existing accessory on host (stop container, remove container, start new container; use NAME=all to boot all accessories)"
+    "remove:Remove accessory container, image and data directory from host (use NAME=all to remove all accessories)"
+    "restart:Restart existing accessory container on host"
+    "start:Start existing accessory container on host"
+    "stop:Stop existing accessory container on host"
+    "upgrade:Upgrade accessories from Kamal 1.x to 2.0 (restart them in 'kamal' network)"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t accessory-commands "Kamal accessory commands" accessory_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (boot|details|exec|logs|reboot|remove|restart|start|stop)
+          # These commands require a NAME parameter
+          if (( CURRENT == 2 )); then
+            # At the NAME position - we could add accessory name completion here
+            # if we had a way to list available accessories
+            _kamal_message "Specify an accessory name (or 'all' for all accessories)" && ret=0
+          elif [[ "$words[1]" == "exec" && CURRENT == 3 ]]; then
+            # For exec, the 3rd argument is a command
+            _kamal_message "Enter a command to execute" && ret=0
+          elif (( CURRENT > 2 )) && [[ "$words[1]" != "exec" || CURRENT > 3 ]]; then
+            _values $_kamal_flags && ret=0
+          fi
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          accessory_subcommands=("${(@)accessory_subcommands:#help*}")
+          _describe -t accessory-help-commands "Kamal accessory help commands" accessory_subcommands
+          ;;
+        (upgrade)
+          # For upgrade, show flags immediately
+          _arguments $_kamal_flags && ret=0
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_app() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a app_subcommands
+  app_subcommands=(
+    "boot:Boot app on servers (or reboot app if already running)"
+    "containers:Show app containers on servers"
+    "details:Show details about app containers"
+    "exec:Execute a custom command on servers within the app container (use --help to show options)"
+    "help:Describe subcommands or one specific subcommand"
+    "images:Show app images on servers"
+    "logs:Show log lines from app on servers (use --help to show options)"
+    "remove:Remove app containers and images from servers"
+    "stale_containers:Detect app stale containers"
+    "start:Start existing app container on servers"
+    "stop:Stop app container on servers"
+    "version:Show app version currently running on servers"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t app-commands "Kamal app commands" app_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (boot|containers|details|images|logs|remove|stale_containers|start|stop)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (exec)
+          # For exec, the next argument is a command
+          if (( CURRENT == 2 )); then
+            _kamal_message "Enter a command to execute" && ret=0
+          else
+            _values $_kamal_flags && ret=0
+          fi
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          app_subcommands=("${(@)app_subcommands:#help*}")
+          _describe -t app-help-commands "Kamal app help commands" app_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_build() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a build_subcommands
+  build_subcommands=(
+    "create:Create a build setup"
+    "deliver:Build app and push app image to registry then pull image on servers"
+    "details:Show build setup"
+    "dev:Build using the working directory, tag it as dirty, and push to local image store."
+    "help:Describe subcommands or one specific subcommand"
+    "pull:Pull app image from registry onto servers"
+    "push:Build and push app image to registry"
+    "remove:Remove build setup"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t build-commands "Kamal build commands" build_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (create|deliver|details|dev|pull|push|remove)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          build_subcommands=("${(@)build_subcommands:#help*}")
+          _describe -t build-help-commands "Kamal build help commands" build_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_help() {
+  local ret=1
+
+  # Make sure kamal_commands is initialized properly
+  # if (( ${#kamal_commands} == 0 )); then
+  #   _kamal_commands >/dev/null
+  # fi
+
+  # If we already have a command after "help", return without suggestions
+  if (( CURRENT > 2 )); then
+    ret=0
+  else
+    local -a help_commands
+    # Filter out help from the list of commands
+    help_commands=("${(@)_kamal_commands:#help}")
+
+    _values 'Kamal help' $help_commands && ret=0
+  fi
+
+  return ret
+}
+
+_kamal_lock() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a lock_subcommands
+  lock_subcommands=(
+    "acquire:Acquire the deploy lock"
+    "help:Describe subcommands or one specific subcommand"
+    "release:Release the deploy lock"
+    "status:Report lock status"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t lock-commands "Kamal lock commands" lock_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (acquire)
+          local -a acquire_flags
+          acquire_flags=(
+            $_kamal_flags
+            '(-m --message)'{-m,--message=}'[A lock message]:message:' # Required flag
+          )
+          _arguments $acquire_flags && ret=0
+          ;;
+        (release|status)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          lock_subcommands=("${(@)lock_subcommands:#help*}")
+          _describe -t lock-help-commands "Kamal lock help commands" lock_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_proxy() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a proxy_subcommands
+  proxy_subcommands=(
+    "boot:Boot proxy on servers"
+    "boot_config:Manage kamal-proxy boot configuration"
+    "details:Show details about proxy container from servers"
+    "help:Describe subcommands or one specific subcommand"
+    "logs:Show log lines from proxy on servers"
+    "reboot:Reboot proxy on servers (stop container, remove container, start new container)"
+    "remove:Remove proxy container and image from servers"
+    "restart:Restart existing proxy container on servers"
+    "start:Start existing proxy container on servers"
+    "stop:Stop existing proxy container on servers"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t proxy-commands "Kamal proxy commands" proxy_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (boot|details|logs|reboot|remove|restart|start|stop)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (boot_config)
+          if (( CURRENT == 2 )); then
+            local -a boot_config_commands=(
+              "set:Set boot configuration"
+              "get:Get boot configuration"
+              "reset:Reset boot configuration"
+            )
+            _describe -t boot-config-commands "Boot config commands" boot_config_commands && ret=0
+          else
+            _values $_kamal_flags && ret=0
+          fi
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          proxy_subcommands=("${(@)proxy_subcommands:#help*}")
+          _describe -t proxy-help-commands "Kamal proxy help commands" proxy_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_prune() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a prune_subcommands
+  prune_subcommands=(
+    "all:Prune unused images and stopped containers"
+    "containers:Prune all stopped containers, except the last n (default 5)"
+    "help:Describe subcommands or one specific subcommand"
+    "images:Prune unused images"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t prune-commands "Kamal prune commands" prune_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (all|containers|images)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          prune_subcommands=("${(@)prune_subcommands:#help*}")
+          _describe -t prune-help-commands "Kamal prune help commands" prune_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_registry() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a registry_subcommands
+  registry_subcommands=(
+    "help:Describe subcommands or one specific subcommand"
+    "login:Log in to registry locally and remotely"
+    "logout:Log out of registry locally and remotely"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t registry-commands "Kamal registry commands" registry_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (help)
+          # Remove help itself from the list of commands
+          registry_subcommands=("${(@)registry_subcommands:#help*}")
+          _describe -t registry-help-commands "Kamal registry help commands" registry_subcommands
+          ;;
+        (login|logout)
+          _arguments $_kamal_flags && ret=0
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_secrets() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a secrets_subcommands
+  secrets_subcommands=(
+    "extract:Extract a single secret from the results of a fetch call"
+    "fetch:Fetch secrets from a vault"
+    "help:Describe subcommands or one specific subcommand"
+    "print:Print the secrets (for debugging)"
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t secrets-commands "Kamal secrets commands" secrets_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (fetch)
+          local -a fetch_flags
+          fetch_flags=(
+            $_kamal_flags
+            '(-a --adapter)'{-a,--adapter=}'[Secret storage adapter]:adapter:(aws-parameter-store)'
+          )
+          _arguments $fetch_flags && ret=0
+          ;;
+        (extract|print)
+          _arguments $_kamal_flags && ret=0
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          secrets_subcommands=("${(@)secrets_subcommands:#help*}")
+          _describe -t secrets-help-commands "Kamal secrets help commands" secrets_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal_server() {
+  local context state line
+  typeset -A opt_args
+  local ret=1
+
+  local -a server_subcommands
+  server_subcommands=(
+    "bootstrap:Set up Docker to run Kamal apps"
+    "exec:Run a custom command on the server (use --help to show options)"
+    "help:Describe subcommands or one specific subcommand"
+  )
+
+  local -a server_flags
+  server_flags=(
+    $_kamal_flags
+    '(-i --interactive --no-interactive --skip-interactive)'{-i,--interactive}'[Run the command interactively]'
+    '(-i --interactive --no-interactive --skip-interactive)--no-interactive[Do not run the command interactively]'
+    '(-i --interactive --no-interactive --skip-interactive)--skip-interactive[Skip interactive mode]'
+  )
+
+  _arguments -C \
+    '1: :->subcmd' \
+    '*:: :->args' && ret=0
+
+  case $state in
+    (subcmd)
+      _describe -t server-commands "Kamal server commands" server_subcommands && ret=0
+      ;;
+    (args)
+      case $words[1] in
+        (bootstrap)
+          _arguments $server_flags && ret=0
+          ;;
+        (exec)
+          if (( CURRENT == 2 )); then
+            # For exec, the next argument is a command
+            _kamal_message "Enter a command to execute" && ret=0
+          else
+            _values $server_flags && ret=0
+          fi
+          ;;
+        (help)
+          # Remove help itself from the list of commands
+          server_subcommands=("${(@)server_subcommands:#help*}")
+          _describe -t server-help-commands "Kamal server help commands" server_subcommands
+          ;;
+      esac
+      ;;
+  esac
+
+  return ret
+}
+
+_kamal "$@"
\ No newline at end of file
diff --git a/plugins/kamal/kamal.plugin.zsh b/plugins/kamal/kamal.plugin.zsh
new file mode 100644
index 000000000..e21ab4f92
--- /dev/null
+++ b/plugins/kamal/kamal.plugin.zsh
@@ -0,0 +1,25 @@
+# Find kamal binary (local ./bin/kamal or global)
+function _kamal_command () {
+  if [ -x "./bin/kamal" ]; then
+    ./bin/kamal "$@"
+  else
+    command kamal "$@"
+  fi
+}
+
+function which-kamal() {
+  if [ -x "./bin/kamal" ]; then
+    echo "Using local ./bin/kamal"
+  else
+    echo "Using global $(command -v kamal)"
+  fi
+}
+
+# Use `_kamal_command`` function for `kamal` command
+alias kamal='_kamal_command'
+
+# Aliases
+alias kad='kamal deploy'
+
+# Hook up completion
+compdef _kamal_command=kamal