ruby-gem-release 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5bb3465b2672800174dc8160f4f3dea172fab317cd9c6698c5e9555838830d9
-  data.tar.gz: 2c5c68af968df8d0a2b834efa4a3dc15c197a0567848588e9c819a2e7218d0db
+  metadata.gz: 6147db94530ebf0d53d63e1988df089cf1d9442721f3d5a45384731e308d5c91
+  data.tar.gz: c5ebef85abb8868a7cfa8f0316a5be602b359443140f399e981b2060f4b59404
 SHA512:
-  metadata.gz: 75c793e1f932297cee9148c38a8fa85d642861f8e5bf884ec1911842fed7fa8ea19067f61f5a7c98e08eb1efabf44902557261cb72383c8f09723393611e0355
-  data.tar.gz: c28d2ccd7ef2588003a20c23c8275bbf3d077c9ecfb2a8cd113fbcc4c45e568c714cdd11a419a492cd291e53dfd08486686ef87612e4ad50cc3051c5773bfdd7
+  metadata.gz: 11ef16efd08c2a7c87c3c3f758b391b20c258bc3bc4b14e1a7a77299a27a971a8746c636aea9035e0d3fe87c87594c9c06829c64d80ff4ab877b28e09e2f1cb5
+  data.tar.gz: c17e11145abae06232754512046f5212c35309da77feef552e11d730e3cc4fb5bc70133c5f44b4df6334f5d586f8f1d8f54d13f3e9962d6243a29e28238304f6

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.1 (2026/11/10)
+
+- [#49](https://github.com/dblock/ruby-gem-release/pull/49): Add ordered lifecycle hooks to standard and semantic workflows, trusted preparation hooks, structured hook failure details, a consumer customization example, and real-Git coverage - [@dblock](https://github.com/dblock).
+
 ## 0.5.0 (2026/11/10)
 
 - [#28](https://github.com/dblock/ruby-gem-release/pull/28): Add success callbacks and structured failure callbacks with captured Ruby exceptions to both Actions interfaces - [@dblock](https://github.com/dblock).

data/README.md

@@ -53,7 +53,7 @@ permissions:
 
 jobs:
   release:
-    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.4.0
+    uses: dblock/ruby-gem-release/.github/workflows/release.yml@v0.5.0
     with:
       ruby-version: '3.3'
       version: ${{ inputs.version }}
@@ -97,6 +97,7 @@ For a real-world example of adding release automation to an existing gem, see [r
 Replace only what you need. The [standard workflow](docs/workflow/ruby_gem.md) preserves ordering; [Detailed Usage](docs/usage.md) provides file examples and complete manual callbacks.
 
 - **Project conventions:** Choose [version objects](docs/usage.md#version-objects) and [changelog formats](docs/usage.md#changelog-objects), including custom implementations.
+- **Stage customization:** Add ordered [lifecycle hooks](docs/workflow/hooks.md) for validation, trusted preparation edits, publication observers, and notifications without replacing the pipeline.
 - **Release decisions and callbacks:** Customize [validation, preparation, publication, and notifications](docs/tasks.md). Callbacks receive an [execution context](docs/execution_context.md) with release data, step history, and the configured workflow.
 - **Semantic releases:** Opt into [Conventional Commits, release-history-based versions, and generated notes](docs/workflow/semantic_ruby_gem.md) without changing the execution platform or registry.
 - **Packages and registries:** Override [package construction](docs/package/ruby_gem.md) or supply a [registry destination](docs/destination.md) independently of hosted releases.

data/lib/ruby-gem-release/execution_context.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'execution_context/step'
+require_relative 'release'
 
 module RubyGemRelease
   class ExecutionContext
-    attr_reader :release, :step, :steps, :workflow, :run, :analysis
+    attr_reader :release, :step, :steps, :workflow, :run, :analysis, :stage, :hook, :hook_index, :failure
 
     def self.step_id(task)
       task
@@ -28,5 +29,23 @@ module RubyGemRelease
     def record_analysis!(decision)
       @state.record_analysis!(decision)
     end
+
+    def with(release: @release, analysis: @analysis, stage: nil, hook: nil, hook_index: nil, failure: @failure)
+      copy = dup
+      { release: release, analysis: analysis, stage: stage, hook: hook, hook_index: hook_index, failure: failure }.each do |name, value|
+        copy.instance_variable_set("@#{name}", value)
+      end
+      copy.freeze
+    end
+
+    def refresh
+      snapshot = @state.snapshot
+      analysis = snapshot.fetch(:analysis)
+      release = if @release
+                  Release.new(version: analysis&.version || @release.version, gemspec_version: @release.gemspec_version, date: @release.date,
+                              next_version: snapshot.fetch(:next_version), notes: analysis&.notes || @release.notes)
+                end
+      with(release: release, analysis: analysis)
+    end
   end
 end

data/lib/ruby-gem-release/release_failure.rb

@@ -3,24 +3,30 @@
 module RubyGemRelease
   class ReleaseFailure
     class CapturedError < StandardError
-      attr_reader :original_class
+      attr_reader :original_class, :stage, :hook, :hook_index
 
-      def self.capture(error)
-        new(original_class: error.class.name || error.class.to_s, message: error.message, backtrace: error.backtrace)
+      def self.capture(error, **details)
+        new(original_class: error.class.name || error.class.to_s, message: error.message, backtrace: error.backtrace, **details)
       end
 
       def self.from_h(attributes)
-        new(original_class: attributes.fetch('class'), message: attributes.fetch('message'), backtrace: attributes.fetch('backtrace'))
+        new(original_class: attributes.fetch('class'), message: attributes.fetch('message'), backtrace: attributes.fetch('backtrace'),
+            stage: attributes['stage'], hook: attributes['hook'], hook_index: attributes['hook_index'])
       end
 
-      def initialize(original_class:, message:, backtrace:)
+      def initialize(original_class:, message:, backtrace:, stage: nil, hook: nil, hook_index: nil)
         @original_class = original_class.freeze
+        @stage = stage&.to_sym
+        @hook = hook&.to_sym
+        @hook_index = hook_index
         super(message)
         set_backtrace(backtrace)
       end
 
       def to_h
-        { 'class' => original_class, 'message' => message, 'backtrace' => backtrace }
+        { 'class' => original_class, 'message' => message, 'backtrace' => backtrace }.merge(
+          { 'stage' => stage&.to_s, 'hook' => hook&.to_s, 'hook_index' => hook_index }.compact
+        )
       end
     end
 

data/lib/ruby-gem-release/tasks.rb

@@ -108,11 +108,28 @@ module RubyGemRelease
 
     def install_workflow_context_tasks
       install_checkpoint_task
+      install_capture_task
+      install_resolve_task
       task(:configure) { with_failure_capture('release:workflow:configure') { Workflow::Environment.new(provider: @provider).configure! } }
-      task(:capture) { with_failure_capture('release:workflow:capture') { Workflow::Environment.new(provider: @provider).capture!(package: @package) } }
+    end
+
+    def install_capture_task
+      task(:capture) do
+        with_failure_capture('release:workflow:capture') do
+          capture_context = @provider.context(release: nil, task: 'release:workflow:capture', state: Workflow::State.new, workflow: @workflow)
+          lifecycle(:capture, capture_context, after_context: -> { context('release:workflow:capture', preparing: true) }) do
+            Workflow::Environment.new(provider: @provider).capture!(package: @package)
+          end
+        end
+      end
+    end
+
+    def install_resolve_task
       task(:resolve) do
         with_failure_capture('release:workflow:resolve') do
-          Workflow::Environment.new(provider: @provider).resolve!(package: @package, destination: @destination, analysis: state.analysis)
+          lifecycle(:resolve_version, context('release:workflow:resolve', preparing: true), after_context: -> { context('release:workflow:resolve') }) do
+            Workflow::Environment.new(provider: @provider).resolve!(package: @package, destination: @destination, analysis: state.analysis)
+          end
         end
       end
     end
@@ -134,20 +151,32 @@ module RubyGemRelease
           next unless @publish
 
           ctx = context('release:publish')
-          @destination.authenticate!(provider: @provider) unless @workflow&.published?(ctx.release)
+          lifecycle(:authenticate, ctx) { @destination.authenticate!(provider: @provider) } unless @workflow&.published?(ctx.release)
           @publish.call(ctx)
         end
       end
     end
 
     def install_result_tasks
-      desc 'Run the release success callback'
-      task :success do
-        with_failure_capture('release:success') { @success&.call(context('release:success')) }
-      end
+      install_success_task
       desc 'Run the release failure callback'
       task :failure do
-        @failure&.call(failure_context)
+        next unless @failure || lifecycle_hooks?(:failure)
+
+        failure = failure_context
+        lifecycle(:failure, failure.context.with(failure: failure)) { @failure&.call(failure) }
+      end
+    end
+
+    def install_success_task
+      desc 'Run the release success callback'
+      task :success do
+        next unless @success || lifecycle_hooks?(:success)
+
+        with_failure_capture('release:success') do
+          ctx = context('release:success')
+          lifecycle(:success, ctx) { @success&.call(ctx) }
+        end
       end
     end
 
@@ -245,10 +274,21 @@ module RubyGemRelease
     def with_failure_capture(task)
       yield
     rescue StandardError => e
-      Workflow::Failure.capture!(@provider.step_id(task), e, provider: @provider)
+      details = @workflow.respond_to?(:failure_details) ? @workflow.failure_details(e) : {}
+      Workflow::Failure.capture!(@provider.step_id(task), e, provider: @provider, **details)
       raise
     end
 
+    def lifecycle(stage, ctx, **, &)
+      return yield unless @workflow.respond_to?(:run_stage)
+
+      @workflow.run_stage(stage, ctx, **, &)
+    end
+
+    def lifecycle_hooks?(stage)
+      @workflow.respond_to?(:hooks?) && @workflow.hooks?(stage)
+    end
+
     def validate_context_versions(*versions)
       pattern = Version::RubyConstant::PATTERN
       versions.compact.each do |value|

data/lib/ruby-gem-release/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyGemRelease
-  VERSION = '0.5.0'
+  VERSION = '0.5.1'
 end

data/lib/ruby-gem-release/workflow/failure.rb

@@ -14,10 +14,10 @@ module RubyGemRelease
           provider.export('RELEASE_FAILED_STEP_ID' => phase)
         end
 
-        def capture!(phase, error, provider: ExecutionProvider.current)
+        def capture!(phase, error, provider: ExecutionProvider.current, **details)
           return unless provider.directory
 
-          captured_error = ReleaseFailure::CapturedError.capture(error)
+          captured_error = ReleaseFailure::CapturedError.capture(error, **details)
           File.open(failure_file(provider), 'w', 0o600) do |file|
             file.write(JSON.generate('phase' => phase, 'error' => captured_error.to_h))
           end

data/lib/ruby-gem-release/workflow/hooks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyGemRelease
+  module Workflow
+    class Hooks
+      STAGES = %i[capture resolve_version validate prepare_release authenticate checkpoint commit_release build_package tag_release
+                  publish_registry push_release publish_hosted_release prepare_next commit_next push_next success failure].freeze
+
+      def initialize
+        @hooks = { before: {}, after: {} }
+      end
+
+      def register(timing, stage, &block)
+        raise ArgumentError, "unknown lifecycle stage: #{stage.inspect}" unless STAGES.include?(stage)
+        raise ArgumentError, 'hook requires a block' unless block
+
+        (@hooks.fetch(timing)[stage] ||= []) << block
+      end
+
+      def registered?(stage)
+        @hooks.values.any? { |stages| !stages.fetch(stage, []).empty? }
+      end
+
+      def run(stage, context, after_context: nil)
+        call_hooks(:before, stage, context)
+        result = yield
+        call_hooks(:after, stage, after_context ? after_context.call : context) unless @hooks.fetch(:after).fetch(stage, []).empty?
+        result
+      rescue StandardError => e
+        record_failure(e, stage: stage)
+        raise
+      end
+
+      def failure_details(error)
+        @failure_error.equal?(error) ? @failure_details : {}
+      end
+
+      private
+
+      def call_hooks(timing, stage, context)
+        @hooks.fetch(timing).fetch(stage, []).each_with_index do |block, index|
+          block.call(context.with(stage: stage, hook: timing, hook_index: index + 1))
+        rescue StandardError => e
+          record_failure(e, stage: stage, hook: timing, hook_index: index + 1)
+          raise
+        end
+      end
+
+      def record_failure(error, **details)
+        return if @failure_error.equal?(error)
+
+        @failure_error = error
+        @failure_details = details
+      end
+    end
+  end
+end

data/lib/ruby-gem-release/workflow/ruby_gem.rb

@@ -5,6 +5,7 @@ require_relative '../package/ruby_gem'
 require_relative '../destination/ruby_gems'
 require_relative '../source_control/git'
 require_relative '../hosting/github_release'
+require_relative 'hooks'
 
 module RubyGemRelease
   module Workflow
@@ -28,6 +29,28 @@ module RubyGemRelease
         @failure = failure
       end
 
+      def before(stage, &)
+        hooks.register(:before, stage, &)
+        self
+      end
+
+      def after(stage, &)
+        hooks.register(:after, stage, &)
+        self
+      end
+
+      def run_stage(stage, context, **, &)
+        hooks.run(stage, context, **, &)
+      end
+
+      def failure_details(error)
+        hooks.failure_details(error)
+      end
+
+      def hooks?(stage)
+        hooks.registered?(stage)
+      end
+
       def install_tasks
         Tasks.install(workflow: self, package: @package, destination: @destination, provider: @provider) do |tasks|
           install_callbacks(tasks)
@@ -35,7 +58,7 @@ module RubyGemRelease
       end
 
       def checkpoint!(context)
-        prepare_publication(context.release)
+        run_stage(:checkpoint, context) { prepare_publication(context) }
       end
 
       def published?(release)
@@ -44,15 +67,25 @@ module RubyGemRelease
 
       private
 
+      def hooks
+        @hooks ||= Hooks.new
+      end
+
       def install_callbacks(tasks)
-        tasks.validate { |ctx| validate_release(ctx) }
-        tasks.prepare { |ctx| prepare_release(ctx.release) }
-        tasks.publish { |ctx| publish(ctx.release) }
+        tasks.validate { |ctx| validate_with_hooks(ctx) }
+        tasks.prepare { |ctx| prepare_release(ctx) }
+        tasks.publish { |ctx| publish(ctx) }
         tasks.bump { |ctx| prepare_next(ctx) }
         tasks.success(&@success) if @success
         tasks.failure(&@failure) if @failure
       end
 
+      def validate_with_hooks(ctx)
+        run_stage(:validate, ctx, after_context: -> { ctx.refresh }) do
+          raise ArgumentError, 'Release validation failed: callback returned false' if validate_release(ctx) == false
+        end
+      end
+
       def validate_release(ctx)
         return @validate.call(ctx) if @validate
 
@@ -61,46 +94,52 @@ module RubyGemRelease
         raise ArgumentError, 'Nothing to release: no pending changelog notes'
       end
 
-      def prepare_release(release)
+      def prepare_release(ctx)
         @git.stage_changes! do
-          select_version!(release.version) unless @provider.fetch('INPUT_VERSION', '').empty?
-          @changelog&.release!(release.with_version(@version.read))
+          run_stage(:prepare_release, ctx) { prepare_release_files(ctx.release) }
         end
       end
 
+      def prepare_release_files(release)
+        select_version!(release.version) unless @provider.fetch('INPUT_VERSION', '').empty?
+        @changelog&.release!(release.with_version(@version.read))
+      end
+
       def select_version!(version)
         raise ArgumentError, 'version object must implement set! when selecting a release version' unless @version.respond_to?(:set!)
 
         @version.set!(version)
       end
 
-      def prepare_publication(release)
-        @git.commit!(release)
-        @package.build!(release)
-        @git.tag!(release)
+      def prepare_publication(ctx)
+        run_stage(:commit_release, ctx) { @git.commit!(ctx.release) }
+        run_stage(:build_package, ctx) { @package.build!(ctx.release) }
+        run_stage(:tag_release, ctx) { @git.tag!(ctx.release) }
       end
 
-      def publish(release)
-        prepare_publication(release)
-        @destination.publish!(release, package: @package)
-        @git.push!(release)
-        @hosting&.publish!(release, package: @package)
+      def publish(ctx)
+        prepare_publication(ctx)
+        run_stage(:publish_registry, ctx) { @destination.publish!(ctx.release, package: @package) }
+        run_stage(:push_release, ctx) { @git.push!(ctx.release) }
+        run_stage(:publish_hosted_release, ctx) { @hosting.publish!(ctx.release, package: @package) } if @hosting
       end
 
       def prepare_next(ctx)
-        next_release = stage_next!(ctx.release)
-        @git.commit_next!(next_release)
-        @git.push!
-        ctx.record_next_version!(next_release.next_version)
+        next_ctx = stage_next!(ctx)
+        run_stage(:commit_next, next_ctx) { @git.commit_next!(next_ctx.release) }
+        run_stage(:push_next, next_ctx) { @git.push! }
+        ctx.record_next_version!(next_ctx.release.next_version)
       end
 
-      def stage_next!(release)
-        next_release = nil
+      def stage_next!(ctx)
+        next_ctx = ctx
         @git.stage_changes! do
-          next_release = release.with_next_version(@version.increment!(from: release.version))
-          @changelog&.prepare_next!(next_release)
+          run_stage(:prepare_next, ctx, after_context: -> { next_ctx }) do
+            next_ctx = ctx.with(release: ctx.release.with_next_version(@version.increment!(from: ctx.release.version)))
+            @changelog&.prepare_next!(next_ctx.release)
+          end
         end
-        next_release
+        next_ctx
       end
     end
   end

data/lib/ruby-gem-release/workflow/semantic_ruby_gem.rb

@@ -20,14 +20,14 @@ module RubyGemRelease
       private
 
       def install_callbacks(tasks)
-        tasks.validate { |ctx| validate_release(ctx) }
-        tasks.prepare { |ctx| prepare_semantic_release(ctx) }
+        tasks.validate { |ctx| validate_with_hooks(ctx) }
+        tasks.prepare { |ctx| prepare_release(ctx) }
         install_result_callbacks(tasks)
         tasks.failure(&@failure) if @failure
       end
 
       def install_result_callbacks(tasks)
-        tasks.publish { |ctx| with_decision(ctx) { publish(ctx.release) } }
+        tasks.publish { |ctx| with_decision(ctx) { publish(ctx) } }
         tasks.bump { |ctx| with_decision(ctx) { prepare_next(ctx) if @bump } }
         tasks.success { |ctx| with_decision(ctx) { @success&.call(ctx) } }
       end
@@ -52,12 +52,14 @@ module RubyGemRelease
         ctx.analysis
       end
 
-      def prepare_semantic_release(ctx)
+      def prepare_release(ctx)
         checked_decision(ctx)
-        @git.stage_changes! do
-          select_version!(ctx.release.version)
-          @changelog&.release!(ctx.release)
-        end
+        super
+      end
+
+      def prepare_release_files(release)
+        select_version!(release.version)
+        @changelog&.release!(release)
       end
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby-gem-release
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Daniel Doubrovkine
 bindir: bin
 cert_chain: []
-date: 2026-11-10 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: commonmarker
@@ -81,6 +81,7 @@ files:
 - lib/ruby-gem-release/version/ruby_constant.rb
 - lib/ruby-gem-release/workflow/environment.rb
 - lib/ruby-gem-release/workflow/failure.rb
+- lib/ruby-gem-release/workflow/hooks.rb
 - lib/ruby-gem-release/workflow/ruby_gem.rb
 - lib/ruby-gem-release/workflow/ruby_gems_credentials.rb
 - lib/ruby-gem-release/workflow/semantic_ruby_gem.rb