Add cask install steps

- Expose structured steps for cask flight phases and API data.
- Prefer steps over matching Ruby flight blocks with warnings.
- Document cask usage and autocorrect simple file preparation.

Author: MikeMcQuaid

Library/Homebrew/cask/artifact.rb

@@ -8,6 +8,7 @@
 require "cask/artifact/binary"
 require "cask/artifact/colorpicker"
 require "cask/artifact/dictionary"
+require "cask/artifact/install_steps"
 require "cask/artifact/font"
 require "cask/artifact/input_method"
 require "cask/artifact/installer"

Library/Homebrew/cask/artifact/abstract_artifact.rb

@@ -69,6 +69,8 @@ def sort_order
         @sort_order ||= T.let(
           [
             PreflightBlock,
+            PreflightSteps,
+            UninstallPreflightSteps,
             # The `uninstall` stanza should be run first, as it may
             # depend on other artifacts still being installed.
             Uninstall,
@@ -99,6 +101,8 @@ def sort_order
             ],
             Binary,
             Manpage,
+            PostflightSteps,
+            UninstallPostflightSteps,
             PostflightBlock,
             Zap,
           ].each_with_index.flat_map { |classes, i| Array(classes).map { |c| [c, i] } }.to_h,

Library/Homebrew/cask/artifact/install_steps.rb

@@ -0,0 +1,75 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "cask/artifact/abstract_artifact"
+require "install_steps"
+
+module Cask
+  module Artifact
+    class AbstractInstallSteps < AbstractArtifact
+      abstract!
+
+      sig { params(cask: Cask, steps: Homebrew::InstallSteps::Steps).void }
+      def initialize(cask, steps)
+        super
+        @steps = T.let(Homebrew::InstallSteps::DSL.normalise_steps(steps), Homebrew::InstallSteps::Steps)
+      end
+
+      sig { returns(Homebrew::InstallSteps::Steps) }
+      attr_reader :steps
+
+      sig { override.returns(T::Array[T.anything]) }
+      def to_args = [{ steps: }]
+
+      sig { override.returns(String) }
+      def summarize
+        ::Utils.pluralize("install step", steps.length, include_count: true)
+      end
+
+      private
+
+      sig { returns(Homebrew::InstallSteps::Runner) }
+      def runner
+        Homebrew::InstallSteps::Runner.new(context: cask)
+      end
+    end
+
+    class PreflightSteps < AbstractInstallSteps
+      sig { params(_options: T.anything).void }
+      def install_phase(**_options)
+        runner.run(steps)
+      end
+
+      sig { params(_options: T.anything).void }
+      def uninstall_phase(**_options)
+        runner.run(steps, phase: :uninstall)
+      end
+    end
+
+    class PostflightSteps < AbstractInstallSteps
+      sig { params(_options: T.anything).void }
+      def install_phase(**_options)
+        runner.run(steps)
+      end
+
+      sig { params(_options: T.anything).void }
+      def uninstall_phase(**_options)
+        runner.run(steps, phase: :uninstall)
+      end
+    end
+
+    class UninstallPreflightSteps < AbstractInstallSteps
+      sig { params(_options: T.anything).void }
+      def uninstall_phase(**_options)
+        runner.run(steps)
+      end
+    end
+
+    class UninstallPostflightSteps < AbstractInstallSteps
+      sig { params(_options: T.anything).void }
+      def uninstall_phase(**_options)
+        runner.run(steps)
+      end
+    end
+  end
+end

Library/Homebrew/cask/dsl.rb

@@ -76,6 +76,20 @@ class DSL
       Artifact::PostflightBlock,
     ].freeze
 
+    INSTALL_STEP_ARTIFACT_CLASSES = [
+      Artifact::PreflightSteps,
+      Artifact::PostflightSteps,
+      Artifact::UninstallPreflightSteps,
+      Artifact::UninstallPostflightSteps,
+    ].freeze
+
+    INSTALL_STEP_FLIGHT_BLOCK_CLASSES = T.let({
+      Artifact::PreflightSteps           => [Artifact::PreflightBlock, :preflight],
+      Artifact::PostflightSteps          => [Artifact::PostflightBlock, :postflight],
+      Artifact::UninstallPreflightSteps  => [Artifact::PreflightBlock, :uninstall_preflight],
+      Artifact::UninstallPostflightSteps => [Artifact::PostflightBlock, :uninstall_postflight],
+    }.freeze, T::Hash[T.untyped, T.untyped])
+
     DSL_METHODS = T.let(Set.new([
       :arch,
       :artifacts,
@@ -121,6 +135,7 @@ class DSL
       *ORDINARY_ARTIFACT_CLASSES.map(&:dsl_key),
       *ACTIVATABLE_ARTIFACT_CLASSES.map(&:dsl_key),
       *ARTIFACT_BLOCK_CLASSES.flat_map { |klass| [klass.dsl_key, klass.uninstall_dsl_key] },
+      *INSTALL_STEP_ARTIFACT_CLASSES.map(&:dsl_key),
     ]).freeze, T::Set[Symbol])
 
     include OnSystem::MacOSAndLinux
@@ -798,11 +813,61 @@ def disable!(date:, because:, replacement: nil, replacement_formula: nil, replac
       [klass.dsl_key, klass.uninstall_dsl_key].each do |dsl_key|
         define_method(dsl_key) do |&block|
           T.bind(self, DSL)
-          artifacts.add(klass.new(cask, dsl_key => block))
+          if install_step_artifact_defined?(dsl_key)
+            warn_on_install_step_conflict(dsl_key, T.must(install_step_artifact_class(dsl_key)).dsl_key)
+          else
+            artifacts.add(klass.new(cask, dsl_key => block))
+          end
         end
       end
     end
 
+    INSTALL_STEP_ARTIFACT_CLASSES.each do |klass|
+      define_method(klass.dsl_key) do |steps = nil, **kwargs, &block|
+        T.bind(self, DSL)
+        steps = if block
+          Homebrew::InstallSteps::DSL.build(default_base: :staged_path, default_source_base: :staged_path,
+                                            default_target_base: :staged_path, &block)
+        else
+          Homebrew::InstallSteps::DSL.normalise_steps([kwargs[:steps] || steps].flatten.compact)
+        end
+        remove_conflicting_flight_blocks(klass)
+        artifacts.add(klass.new(cask, steps))
+      end
+    end
+
+    sig { params(dsl_key: Symbol).returns(T::Boolean) }
+    def install_step_artifact_defined?(dsl_key)
+      return false unless (klass = install_step_artifact_class(dsl_key))
+
+      artifacts.any?(klass)
+    end
+
+    sig { params(dsl_key: Symbol).returns(T.nilable(T.class_of(Artifact::AbstractInstallSteps))) }
+    def install_step_artifact_class(dsl_key)
+      INSTALL_STEP_FLIGHT_BLOCK_CLASSES.find do |_step_class, (_block_class, block_dsl_key)|
+        block_dsl_key == dsl_key
+      end&.first
+    end
+
+    sig { params(klass: T.class_of(Artifact::AbstractInstallSteps)).void }
+    def remove_conflicting_flight_blocks(klass)
+      flight_block_class, dsl_key = INSTALL_STEP_FLIGHT_BLOCK_CLASSES.fetch(klass)
+      conflicting_flight_blocks = artifacts.select do |artifact|
+        artifact.is_a?(flight_block_class) && T.unsafe(artifact).directives.key?(dsl_key)
+      end
+
+      conflicting_flight_blocks.each do |artifact|
+        warn_on_install_step_conflict(dsl_key, klass.dsl_key)
+        artifacts.delete(artifact)
+      end
+    end
+
+    sig { params(dsl_key: Symbol, steps_key: Symbol).void }
+    def warn_on_install_step_conflict(dsl_key, steps_key)
+      opoo "#{token}: `#{dsl_key}` is ignored because `#{steps_key}` is defined!"
+    end
+
     sig { override.params(method: Symbol, _args: T.anything).returns(T.noreturn) }
     def method_missing(method, *_args)
       raise NoMethodError, "undefined method '#{method}' for Cask '#{token}'"

Library/Homebrew/cask/installer.rb

@@ -331,6 +331,8 @@ def install_artifacts(predecessor: nil)
             Artifact::KeyboardLayout,
             Artifact::Mdimporter,
             Artifact::Moved,
+            Artifact::PostflightSteps,
+            Artifact::PreflightSteps,
             Artifact::Pkg,
             Artifact::Qlplugin,
             Artifact::Symlinked,
@@ -652,9 +654,13 @@ def uninstall_artifacts(clear: false, successor: nil, quit: true)
               Artifact::GeneratedCompletion,
               Artifact::KeyboardLayout,
               Artifact::Moved,
+              Artifact::PostflightSteps,
+              Artifact::PreflightSteps,
               Artifact::Qlplugin,
               Artifact::Symlinked,
               Artifact::Uninstall,
+              Artifact::UninstallPostflightSteps,
+              Artifact::UninstallPreflightSteps,
             ),
           )
 

Library/Homebrew/json_api_postinstall_preflight_postflight_plan.md

@@ -113,7 +113,7 @@ Local scan source: `homebrew/cask` at `4ed4e04eaa5`.
   paths to `prefix`; expose the ordered array through `FormulaStruct`; make
   `post_install_steps` take precedence over `post_install`; document that the
   two forms must not be mixed.
-- [ ] PR 3, cask flight steps.
+- [x] PR 3, cask flight steps.
   Commit: `Add cask install steps`.
   Scope: cask artifacts for `preflight_steps`, `postflight_steps`,
   `uninstall_preflight_steps` and `uninstall_postflight_steps`, cask API

Library/Homebrew/rubocops/cask/install_steps.rb

@@ -8,6 +8,7 @@ module Cop
     module Cask
       # This cop checks declarative install step usage.
       class InstallSteps < Base
+        extend AutoCorrector
         include CaskHelp
         include ::RuboCop::Cop::InstallStepsHelper
 
@@ -26,10 +27,15 @@ def on_cask(cask_block)
           stanzas = cask_block.stanzas
           INSTALL_STEP_PAIRS.each do |flight_block, steps_block|
             next unless (flight_stanza = stanzas.find { |stanza| stanza.stanza_name == flight_block })
-            next unless (steps_stanza = stanzas.find { |stanza| stanza.stanza_name == steps_block })
 
-            add_offense(steps_stanza.source_range,
-                        message: "`#{flight_stanza.stanza_name}` and `#{steps_block}` cannot both be used.")
+            steps_stanza = stanzas.find { |stanza| stanza.stanza_name == steps_block }
+
+            if steps_stanza
+              add_offense(steps_stanza.source_range,
+                          message: "`#{flight_stanza.stanza_name}` and `#{steps_block}` cannot both be used.")
+            else
+              audit_flight_block(flight_stanza, steps_block)
+            end
           end
 
           stanzas.each do |stanza|
@@ -41,6 +47,28 @@ def on_cask(cask_block)
             add_offense(offense_node, message: STEP_BLOCK_MSG)
           end
         end
+
+        private
+
+        sig { params(flight_stanza: RuboCop::Cask::AST::Stanza, steps_block: Symbol).void }
+        def audit_flight_block(flight_stanza, steps_block)
+          return unless flight_stanza.method_node.block_type?
+
+          block_node = T.cast(flight_stanza.method_node, RuboCop::AST::BlockNode)
+          step_lines = simple_install_step_lines(block_node.body,
+                                                 default_base:        :staged_path,
+                                                 default_source_base: :staged_path,
+                                                 default_target_base: :staged_path)
+          return if step_lines.blank?
+
+          add_offense(block_node.source_range,
+                      message: format(SIMPLE_STEP_CONVERSION_MSG, steps_block:)) do |corrector|
+            corrector.replace(
+              block_node.source_range,
+              install_steps_block_source(steps_block, step_lines, block_node.source_range.column),
+            )
+          end
+        end
       end
     end
   end

Library/Homebrew/sorbet/rbi/dsl/cask/cask.rbi

@@ -0,0 +1,78 @@
+# typed: false
+# frozen_string_literal: true
+
+RSpec.describe Cask::Artifact::PreflightSteps, :cask do
+  let(:cask) do
+    Cask::Cask.new("with-install-steps") do
+      version "1.2.3"
+      sha256 :no_check
+      url "file://#{TEST_FIXTURE_DIR}/cask/container.zip"
+
+      preflight_steps do
+        mkdir_p "Prepared"
+        touch "Prepared/touched"
+      end
+
+      postflight_steps do
+        mv "move-source", "Prepared/moved"
+        ln_s "Prepared/moved", "PreparedLink", source_base: :relative, uninstall: true
+      end
+
+      uninstall_preflight_steps do
+        mkdir "UninstallPrepared"
+        touch "UninstallPrepared/touched"
+      end
+
+      uninstall_postflight_steps do
+        move_children "UninstallPrepared", "UninstallMoved"
+      end
+    end
+  end
+
+  it "runs structured steps through installer artifact phases" do
+    cask.staged_path.mkpath
+    cask.config_path.dirname.mkpath
+    (cask.staged_path/"move-source").write "moved"
+
+    installer = Cask::Installer.new(cask, command: NeverSudoSystemCommand)
+    installer.install_artifacts
+
+    expect(cask.staged_path/"Prepared").to be_a_directory
+    expect(cask.staged_path/"Prepared/touched").to exist
+    expect(cask.staged_path/"Prepared/moved").to exist
+    expect(cask.staged_path/"PreparedLink").to be_a_symlink
+
+    installer.uninstall_artifacts
+
+    expect(cask.staged_path/"PreparedLink").not_to exist
+    expect(cask.staged_path/"UninstallMoved/touched").to exist
+  end
+
+  it "ignores a flight block when matching steps are defined" do
+    cask = nil
+    expect do
+      cask = Cask::Cask.new("with-install-steps-conflict") do
+        version "1.2.3"
+        sha256 :no_check
+        url "file://#{TEST_FIXTURE_DIR}/cask/container.zip"
+
+        preflight do
+          touch "ruby-block-ran"
+        end
+
+        preflight_steps do
+          touch "steps-ran"
+        end
+      end
+    end.to output(/`preflight` is ignored because `preflight_steps` is defined/).to_stderr
+
+    cask = T.must(cask)
+    cask.staged_path.mkpath
+    cask.config_path.dirname.mkpath
+
+    Cask::Installer.new(cask, command: NeverSudoSystemCommand).install_artifacts
+
+    expect(cask.staged_path/"ruby-block-ran").not_to exist
+    expect(cask.staged_path/"steps-ran").to exist
+  end
+end