Add completions_from_executable artifact for Casks

Adds a new DSL stanza for casks to generate shell completions
by running the installed executable:

    cask "mycli" do
      binary "mycli"
      completions_from_executable "mycli", shell_parameter_format: :cobra
    end

This works as a proper artifact (like `binary`, `app`, etc.) that:
- Automatically generates completions for bash, zsh, fish (and pwsh with :cobra/:typer)
- Automatically removes generated files on uninstall
- Supports all shell_parameter_format options from Formula

Closes #18092

Made-with: Cursor

Author: tiluckdave

Library/Homebrew/cask/artifact.rb

@@ -25,6 +25,7 @@
 require "cask/artifact/bashcompletion"
 require "cask/artifact/fishcompletion"
 require "cask/artifact/zshcompletion"
+require "cask/artifact/generated_completion"
 require "cask/artifact/service"
 require "cask/artifact/stage_only"
 require "cask/artifact/suite"

Library/Homebrew/cask/artifact/generated_completion.rb

@@ -0,0 +1,167 @@
+# typed: true
+# frozen_string_literal: true
+
+require "cask/artifact/abstract_artifact"
+require "utils/popen"
+
+module Cask
+  module Artifact
+    # Artifact corresponding to the `completions_from_executable` stanza.
+    #
+    # Generates shell completions by running the cask's executable.
+    class GeneratedCompletion < AbstractArtifact
+      sig { override.returns(String) }
+      def self.english_name
+        "Generated Completion"
+      end
+
+      sig { override.returns(Symbol) }
+      def self.dsl_key
+        :completions_from_executable
+      end
+
+      sig { returns(Pathname) }
+      attr_reader :executable
+
+      sig { returns(T::Array[String]) }
+      attr_reader :subcommands
+
+      sig { returns(String) }
+      attr_reader :base_name
+
+      sig { returns(T.nilable(T.any(Symbol, String))) }
+      attr_reader :shell_parameter_format
+
+      sig { returns(T::Array[Symbol]) }
+      attr_reader :shells
+
+      sig { params(cask: Cask, executable: T.any(String, Pathname), args: T.untyped).void }
+      def initialize(cask, executable, *args)
+        super(cask)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        @subcommands = T.let(args.map(&:to_s), T::Array[String])
+        @executable = T.let(staged_path_join_executable(executable), Pathname)
+        @shell_parameter_format = T.let(options[:shell_parameter_format], T.nilable(T.any(Symbol, String)))
+        @base_name = T.let(options[:base_name] || cask.token, String)
+        @shells = T.let(
+          options[:shells] || default_completion_shells(@shell_parameter_format),
+          T::Array[Symbol],
+        )
+      end
+
+      sig { override.returns(String) }
+      def summarize
+        "#{executable} generates completions for #{shells.join(", ")}"
+      end
+
+      def install_phase(command: SystemCommand, **_options)
+        generate_completions(command:)
+      end
+
+      def uninstall_phase(command: SystemCommand, **_options)
+        remove_completions(command:)
+      end
+
+      private
+
+      sig { params(command: T.class_of(SystemCommand)).void }
+      def generate_completions(command:)
+        completion_script_path_map = {
+          bash: config.bash_completion/base_name,
+          zsh:  config.zsh_completion/"_#{base_name}",
+          fish: config.fish_completion/"#{base_name}.fish",
+          pwsh: config.pwsh_completion/"_#{base_name}.ps1",
+        }
+
+        shells.each do |shell|
+          popen_read_env = { "SHELL" => shell.to_s }
+          script_path = completion_script_path_map[shell]
+          next if script_path.nil?
+
+          shell_parameter = completion_shell_parameter(
+            shell_parameter_format,
+            shell,
+            executable.to_s,
+            popen_read_env,
+          )
+
+          popen_read_args = []
+          popen_read_args << executable.to_s
+          popen_read_args.concat(subcommands)
+          popen_read_args << shell_parameter if shell_parameter.present?
+          popen_read_args.flatten!
+
+          popen_read_options = {}
+          popen_read_options[:err] = :err unless ENV["HOMEBREW_STDERR"]
+
+          ohai "Generating #{shell} completion for #{base_name}"
+          script_path.dirname.mkpath
+          script_path.write ::Utils.safe_popen_read(popen_read_env, *popen_read_args, **popen_read_options)
+        end
+      end
+
+      sig { params(command: T.class_of(SystemCommand)).void }
+      def remove_completions(command:)
+        [
+          config.bash_completion/base_name,
+          config.zsh_completion/"_#{base_name}",
+          config.fish_completion/"#{base_name}.fish",
+          config.pwsh_completion/"_#{base_name}.ps1",
+        ].each do |path|
+          next unless path.exist?
+
+          ohai "Removing #{path.basename}"
+          path.delete
+        end
+      end
+
+      sig { params(format: T.nilable(T.any(Symbol, String))).returns(T::Array[Symbol]) }
+      def default_completion_shells(format)
+        case format
+        when :cobra, :typer
+          [:bash, :zsh, :fish, :pwsh]
+        else
+          [:bash, :zsh, :fish]
+        end
+      end
+
+      sig {
+        params(
+          format:     T.nilable(T.any(Symbol, String)),
+          shell:      Symbol,
+          executable: String,
+          env:        T::Hash[String, String],
+        ).returns(T.nilable(T.any(String, T::Array[String])))
+      }
+      def completion_shell_parameter(format, shell, executable, env)
+        shell_parameter = (shell == :pwsh) ? "powershell" : shell.to_s
+
+        case format
+        when nil
+          shell_parameter
+        when :arg
+          "--shell=#{shell_parameter}"
+        when :clap
+          env["COMPLETE"] = shell_parameter
+          nil
+        when :click
+          prog_name = File.basename(executable).upcase.tr("-", "_")
+          env["_#{prog_name}_COMPLETE"] = "#{shell_parameter}_source"
+          nil
+        when :cobra
+          ["completion", shell_parameter]
+        when :flag
+          "--#{shell_parameter}"
+        when :none
+          nil
+        when :typer
+          env["_TYPER_COMPLETE_TEST_DISABLE_SHELL_DETECTION"] = "1"
+          ["--show-completion", shell_parameter]
+        else
+          "#{format}#{shell}"
+        end
+      end
+    end
+  end
+end

Library/Homebrew/cask/dsl.rb

@@ -61,6 +61,7 @@ class DSL
       Artifact::ZshCompletion,
       Artifact::FishCompletion,
       Artifact::BashCompletion,
+      Artifact::GeneratedCompletion,
       Artifact::Uninstall,
       Artifact::Zap,
     ].freeze

Library/Homebrew/test/cask/artifact/generated_completion_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "cask/artifact/generated_completion"
+
+RSpec.describe Cask::Artifact::GeneratedCompletion, :cask do
+  let(:cask) { Cask::CaskLoader.load(cask_path("basic-cask")) }
+  let(:config) { cask.config }
+
+  let(:executable) do
+    (mktmpdir/"test-cli").tap do |path|
+      path.write <<~BASH
+        #!/bin/bash
+        case "$1" in
+          completion)
+            case "$2" in
+              bash) echo "# bash completion for test-cli" ;;
+              zsh) echo "#compdef test-cli" ;;
+              fish) echo "# fish completion for test-cli" ;;
+              powershell) echo "# pwsh completion for test-cli" ;;
+            esac
+            ;;
+        esac
+      BASH
+      FileUtils.chmod "+x", path
+    end
+  end
+
+  describe "#install_phase" do
+    subject(:artifact) do
+      described_class.new(cask, executable, "completion", base_name: "test-cli")
+    end
+
+    after do
+      [
+        config.bash_completion/"test-cli",
+        config.zsh_completion/"_test-cli",
+        config.fish_completion/"test-cli.fish",
+        config.pwsh_completion/"_test-cli.ps1",
+      ].each { |p| p.delete if p.exist? }
+    end
+
+    it "generates completion scripts for bash, zsh, and fish by default" do
+      artifact.install_phase(command: NeverSudoSystemCommand)
+
+      expect(config.bash_completion/"test-cli").to be_a_file
+      expect(config.zsh_completion/"_test-cli").to be_a_file
+      expect(config.fish_completion/"test-cli.fish").to be_a_file
+    end
+
+    it "generates completion scripts with correct content" do
+      artifact.install_phase(command: NeverSudoSystemCommand)
+
+      expect((config.bash_completion/"test-cli").read).to include("bash completion")
+      expect((config.zsh_completion/"_test-cli").read).to include("#compdef")
+      expect((config.fish_completion/"test-cli.fish").read).to include("fish completion")
+    end
+  end
+
+  describe "#install_phase with :cobra format" do
+    subject(:artifact) do
+      described_class.new(cask, executable, base_name: "test-cli", shell_parameter_format: :cobra)
+    end
+
+    after do
+      [
+        config.bash_completion/"test-cli",
+        config.zsh_completion/"_test-cli",
+        config.fish_completion/"test-cli.fish",
+        config.pwsh_completion/"_test-cli.ps1",
+      ].each { |p| p.delete if p.exist? }
+    end
+
+    it "generates pwsh completions when :cobra format is used" do
+      artifact.install_phase(command: NeverSudoSystemCommand)
+
+      expect(config.pwsh_completion/"_test-cli.ps1").to be_a_file
+      expect((config.pwsh_completion/"_test-cli.ps1").read).to include("pwsh completion")
+    end
+  end
+
+  describe "#install_phase with custom shells" do
+    subject(:artifact) do
+      described_class.new(cask, executable, "completion", base_name: "test-cli", shells: [:zsh])
+    end
+
+    after do
+      (config.zsh_completion/"_test-cli").delete if (config.zsh_completion/"_test-cli").exist?
+    end
+
+    it "respects custom shells parameter" do
+      artifact.install_phase(command: NeverSudoSystemCommand)
+
+      expect(config.bash_completion/"test-cli").not_to exist
+      expect(config.zsh_completion/"_test-cli").to be_a_file
+      expect(config.fish_completion/"test-cli.fish").not_to exist
+    end
+  end
+
+  describe "#uninstall_phase" do
+    subject(:artifact) do
+      described_class.new(cask, executable, base_name: base_name)
+    end
+
+    let(:base_name) { "test-removal" }
+
+    before do
+      config.bash_completion.mkpath
+      config.zsh_completion.mkpath
+      config.fish_completion.mkpath
+      config.pwsh_completion.mkpath
+
+      (config.bash_completion/base_name).write("bash")
+      (config.zsh_completion/"_#{base_name}").write("zsh")
+      (config.fish_completion/"#{base_name}.fish").write("fish")
+      (config.pwsh_completion/"_#{base_name}.ps1").write("pwsh")
+    end
+
+    it "removes all generated completion files" do
+      artifact.uninstall_phase(command: NeverSudoSystemCommand)
+
+      expect(config.bash_completion/base_name).not_to exist
+      expect(config.zsh_completion/"_#{base_name}").not_to exist
+      expect(config.fish_completion/"#{base_name}.fish").not_to exist
+      expect(config.pwsh_completion/"_#{base_name}.ps1").not_to exist
+    end
+
+    it "does not fail if files do not exist" do
+      # Remove files first
+      (config.bash_completion/base_name).delete
+      (config.zsh_completion/"_#{base_name}").delete
+      (config.fish_completion/"#{base_name}.fish").delete
+      (config.pwsh_completion/"_#{base_name}.ps1").delete
+
+      expect { artifact.uninstall_phase(command: NeverSudoSystemCommand) }.not_to raise_error
+    end
+  end
+
+  describe "#summarize" do
+    subject(:artifact) do
+      described_class.new(cask, executable, "completion", base_name: "test-cli")
+    end
+
+    it "returns a summary string" do
+      expect(artifact.summarize).to include("test-cli")
+      expect(artifact.summarize).to include("bash")
+    end
+  end
+end