hecks 2.9.0 → 3.0.1

data/lib/hecks/hecks/adapters/codebase/gem_registry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "hecks/release/runner/commands"
+require_relative "secret_vault"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `GemRegistry` adapter: what a release does with rubygems.org and the `gem` program.
+      #
+      # It asks the registry which versions are out (over `curl`, no credentials), builds the gem
+      # from the checkout's gemspec, and pushes it with the key the SecretVault holds. A built gem
+      # file is always deleted again, whether the push worked or not.
+      class GemRegistry
+        # Where RubyGems lists the published versions of the gem.
+        VERSIONS_URL = "https://rubygems.org/api/v1/versions/hecks.json"
+
+        # The env file `op run` reads the push key from, relative to the checkout.
+        ENV_FILE = "release/gem_push.env"
+
+        # @param root [String] the checkout's root
+        # @param commands [#capture, #run!] starts each process
+        # @param vault [SecretVault, nil] holds the push key; one over `commands` when nil
+        def initialize(root:, commands:, vault: nil)
+          @root = root
+          @commands = commands
+          @vault = vault || SecretVault.new(commands: commands)
+        end
+
+        # Says whether RubyGems lists the gem at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Hecks::Release::Runner::Refusal] when RubyGems cannot be reached or answers with
+        #   something that is not a version list
+        def published?(version)
+          result = @commands.capture("curl", "-fsS", VERSIONS_URL, chdir: @root)
+          unless result.success?
+            raise Release::Runner::Refusal, "could not list published hecks versions (#{result.stderr.strip}); " \
+                                            "check the network and re-run"
+          end
+
+          JSON.parse(result.stdout).any? { |entry| entry["number"] == version }
+        rescue JSON::ParserError
+          raise Release::Runner::Refusal, "RubyGems answered with something other than a version list; " \
+                                          "re-run in a minute"
+        end
+
+        # Builds the gem, to prove it builds, and deletes it again.
+        #
+        # @param version [String] the version being released
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the build fails
+        def build_only!(version)
+          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
+        ensure
+          discard(version)
+        end
+
+        # Builds the gem and pushes it to rubygems.org, then deletes the file.
+        #
+        # @param version [String] the version being released
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the build or the push fails
+        def push!(version)
+          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
+          @vault.run!(ENV_FILE, "gem", "push", "hecks-#{version}.gem", chdir: @root)
+        ensure
+          discard(version)
+        end
+
+        private
+
+        def discard(version) = FileUtils.rm_f(File.join(@root, "hecks-#{version}.gem"))
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/kernel_tables.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require "hecks/kernel_capabilities"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `KernelRun` asks of the working tree: projecting the capability enums the
+      # hand-written Rust kernel is matched against, and checking that each capability the grammar
+      # admits has its hand-written file.
+      #
+      # The projection is built in memory by `KernelCapabilities`, the code
+      # `hecks project_kernel_capabilities` runs, and compared with the tree; it writes only when
+      # confirmed. The coverage check reads the tree and writes nothing.
+      module KernelTables
+        # Every operation this family carries out.
+        OPERATIONS = %w[project_kernel_capabilities measure_kernel_coverage].freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `KernelRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture] unused; the family starts no child process
+        # @return [String] the drift report, or the coverage report
+        # @raise [ConsoleCapture::Failure] when a capability has no kernel file
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          confirm = (held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]) == true
+          return coverage(tree) if operation == "measure_kernel_coverage"
+
+          result = KernelCapabilities.build(root: tree.root)
+          tree.apply(result.content, stale: result.stale, confirm: confirm)
+        end
+
+        # Lists every capability the live grammar admits with whether its file is there.
+        #
+        # @param tree [Tree] the checkout
+        # @return [String] one line for each capability, and a verdict
+        # @raise [ConsoleCapture::Failure] when any capability has no file
+        def coverage(tree)
+          lines, verdict, complete = KernelCapabilities.coverage_report(root: tree.root)
+          report = [lines, "", verdict].join("\n")
+          return report if complete
+
+          raise ConsoleCapture::Failure, report
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/language.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "tree"
+require_relative "../shell"
+require "hecks/projection_files"
+require "hecks/grammar/evolve"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `LanguageRun` asks of the working tree: projecting the language's tables
+      # and walking a word through its lifecycle.
+      #
+      # A projection is built in memory by {ProjectionFiles} (the same code the `hecks project_*`
+      # scripts run) and compared with the tree; it writes only when confirmed. An evolution edits
+      # the syntax tables through {Grammar::Evolve}: unconfirmed it is rehearsed against an
+      # in-memory copy and reports the edit it would make; confirmed it regenerates the golden IR
+      # and holds the gates in a child process, and puts every file back if a gate refuses.
+      module Language
+        # The projection each operation runs.
+        PROJECTIONS = {
+          "project_model"             => :model,
+          "project_vocabulary"        => :vocabulary,
+          "project_rust_vocabulary"   => :rust_vocabulary,
+          "project_reserved_names"    => :reserved_names,
+          "project_parser_table"      => :parser_table,
+          "project_bootstrap_table"   => :bootstrap_table,
+          "project_field_hints"       => :field_hints,
+          "project_expression_tables" => :expression_tables,
+          "project_reference"         => :reference
+        }.freeze
+
+        # The status each word or argument operation moves a row to.
+        STATUSES = { "admit" => "admitted", "deprecate" => "deprecated", "retire" => "retired",
+                     "admit_argument" => "admitted", "deprecate_argument" => "deprecated",
+                     "retire_argument" => "retired" }.freeze
+
+        # Every operation this family carries out.
+        OPERATIONS = (PROJECTIONS.keys + %w[propose rename propose_argument] + STATUSES.keys).freeze
+
+        # The specs that hold a grammar edit: the syntax rows agree with the builder, the lifecycle
+        # holds, and the golden IR is the one the language produces.
+        GATES = %w[spec/syntax_conformance_spec.rb spec/syntax_lifecycle_spec.rb spec/ir_golden_spec.rb].freeze
+
+        # The golden IR a grammar edit regenerates.
+        GOLDEN = "spec/golden/ir/Bluebook.json"
+
+        # What the tool says after a proposal or a rename, which still needs hand work.
+        FOLLOW_UP = {
+          "propose"          => "Proposed. It reaches no projection until admitted. Before `hecks admit`:\n  " \
+                                "1. teach the %<context>s builder the word (and its spec/dsl_spec example)",
+          "rename"           => "Renamed. The old spelling keeps parsing — that is the point. Before this holds:\n  " \
+                                "1. alias the new word to the old in the %<context>s builder " \
+                                "(alias_method :%<new_name>s, :%<word>s)\n  " \
+                                "2. add the identical-IR example to spec/dsl_spec.rb",
+          "propose_argument" => "Proposed. It reaches no projection until admitted. Before " \
+                                "`hecks admit_argument`:\n  " \
+                                "1. teach the %<context>s builder's %<word>s method the argument"
+        }.freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `LanguageRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture] starts the gates' child process
+        # @return [String] what was found, or done
+        # @raise [ConsoleCapture::Failure] when the language refuses the edit, or a gate does
+        def call(operation, held, tree, shell: Shell.new)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          return project(operation, args, tree) if PROJECTIONS.key?(operation)
+
+          evolve(operation, args, tree, shell)
+        end
+
+        # Where every word stands: the rows not simply admitted, and the renamed ones.
+        #
+        # @return [String] a count, then a line for each row that is moving or renamed
+        def word_status
+          rows = Grammar::Evolve.keyword_rows
+          moving = rows.reject { |row| row[:status] == "admitted" }
+          renamed = rows.reject { |row| row[:was].to_s.empty? }
+          lines = ["#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"]
+          lines += moving.map { |row| "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
+          lines += renamed.map { |row| "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
+          lines.join("\n")
+        end
+
+        # @param operation [String] a projection's operation
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @return [String] the projected text for `stdout`, or the drift report
+        # @raise [ConsoleCapture::Failure] when the language cannot be projected
+        def project(operation, args, tree)
+          result = ProjectionFiles.build(PROJECTIONS.fetch(operation), root: tree.root)
+          return result.content.values.first if args[:stdout]
+
+          tree.apply(result.content, stale: result.stale, confirm: args[:confirm] == true)
+        rescue ProjectionFiles::Refused => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param operation [String] a word or argument operation
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the gates
+        # @return [String] the rehearsed edit, or the confirmed edit's outcome
+        # @raise [ConsoleCapture::Failure] when the language or a gate refuses
+        def evolve(operation, args, tree, shell)
+          change = -> { edit(operation, args) }
+          return rehearse(change, tree) unless args[:confirm] == true
+
+          guarded(operation, args, tree, shell, change)
+        rescue Grammar::Evolve::Refusal => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param edit [#call] the edit to make
+        # @param tree [Tree] the checkout
+        # @return [String] each file the edit would change, with its lines added and removed
+        def rehearse(edit, tree)
+          changed = Grammar::Evolve.rehearse(&edit)
+          lines = changed.map do |path, text|
+            before = File.read(path).lines
+            after = text.lines
+            "  changed #{tree.relative(path)} (+#{(after - before).size} -#{(before - after).size} lines)"
+          end
+          ["dry run, #{changed.size} file changes (add --confirm to make them, regenerate the golden and hold the gates):",
+           *lines].join("\n")
+        end
+
+        # Makes the edit, regenerates the golden and holds the gates; puts every file back if the
+        # edit or a gate refuses.
+        #
+        # @param operation [String] the operation, for the follow-up it prints
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the child processes
+        # @param edit [#call] the edit to make
+        # @return [String] what the gates held, and what is left to do by hand
+        # @raise [ConsoleCapture::Failure] when the edit or a gate refuses; nothing was changed
+        def guarded(operation, args, tree, shell, edit)
+          paths = Grammar::Evolve.syntax_paths + [tree.path(GOLDEN)]
+          snapshots = paths.to_h { |path| [path, File.read(path)] }
+          Grammar::Evolve.restore_on_raise(paths, &edit)
+          regenerate(tree, shell)
+          gates = shell.capture("bundle", "exec", "rspec", *GATES, chdir: tree.root)
+          unless gates.ok?
+            snapshots.each { |path, text| File.write(path, text) }
+            raise ConsoleCapture::Failure,
+                  "RESTORED — the gates refused, and the failures are the checklist. Nothing was " \
+                  "changed.\n#{[gates.out, gates.err].join.strip}"
+          end
+          ["#{args[:context]}.#{args[:word]} — the gates hold. Regenerated projections and the golden " \
+           "are in the tree.", follow_up(operation, args)].compact.join("\n")
+        end
+
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the child process
+        # @return [void]
+        def regenerate(tree, shell)
+          shell.capture("bundle", "exec", "rspec", "spec/ir_golden_spec.rb", env:   { "GOLDEN" => "rewrite" },
+                                                                             chdir: tree.root)
+        end
+
+        # @param operation [String] the operation
+        # @param args [Hash] the record's plain fields
+        # @return [String, nil] what still needs hand work, if anything
+        def follow_up(operation, args)
+          text = FOLLOW_UP[operation] or return nil
+
+          format(text, context: args[:context], new_name: args[:new_name], word: args[:word])
+        end
+
+        # Makes one edit to the syntax tables.
+        #
+        # @param operation [String] a word or argument operation
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        # @raise [Grammar::Evolve::Refusal] when the tables refuse the edit
+        def edit(operation, args)
+          case operation
+          when "propose" then propose(args)
+          when "rename" then rename(args)
+          when "propose_argument" then propose_argument(args)
+          when "admit", "deprecate", "retire" then set_status(operation, args)
+          else set_argument_status(operation, args)
+          end
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def propose(args)
+          Grammar::Evolve.propose(word: args[:word], context: args[:context], body: args[:body] || "none",
+                                  inner: args[:inner] || "", opens: args[:opens] || "", fills: args[:fills] || "")
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        # @raise [Grammar::Evolve::Refusal] when no new name was given
+        def rename(args)
+          to = args[:new_name] or refuse("a rename goes somewhere: new_name=")
+          Grammar::Evolve.rename(word: args[:word], context: args[:context], to: to)
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def propose_argument(args)
+          Grammar::Evolve.propose_argument(keyword: args[:word], context: args[:context], kind: args[:kind],
+                                           required: args[:required] || "false", at: args[:at] || "",
+                                           named: args[:named] || "", fills: args[:fills] || "",
+                                           pairs_shape: args[:pairs_shape])
+        end
+
+        # @param operation [String] `admit`, `deprecate` or `retire`
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def set_status(operation, args)
+          Grammar::Evolve.set_status(word: args[:word], context: args[:context], to: STATUSES.fetch(operation))
+        end
+
+        # @param operation [String] the argument form of `admit`, `deprecate` or `retire`
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def set_argument_status(operation, args)
+          Grammar::Evolve.set_argument_status(keyword: args[:word], context: args[:context],
+                                              to: STATUSES.fetch(operation), at: args[:at] || "",
+                                              named: args[:named] || "")
+        end
+
+        # @param message [String] why the edit cannot be made
+        # @raise [Grammar::Evolve::Refusal] always
+        def refuse(message) = raise(Grammar::Evolve::Refusal, message)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/npm_registry.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "hecks/release/runner/commands"
+require_relative "secret_vault"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `NpmRegistry` adapter: what a release does with npm and the `@hecks/client` package.
+      #
+      # It asks npm whether a version is out (no credentials), installs the package's
+      # dependencies, and publishes it, either as a dry run (a pack, no credentials) or with the
+      # token the SecretVault holds. The token bypasses 2FA, so the publish runs with
+      # `--auth-type=web` and its output is not captured: the approval link reaches the terminal.
+      class NpmRegistry
+        # The package, by name.
+        PACKAGE = "@hecks/client"
+
+        # Where the package stands, relative to the checkout.
+        PACKAGE_DIR = "packages/hecks-client"
+
+        # The env file `op run` reads the publish token from, relative to the checkout.
+        ENV_FILE = "release/npm_publish.env"
+
+        # The npmrc line that reads the token from the environment `op run` sets.
+        USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}"
+
+        # @param root [String] the checkout's root
+        # @param commands [#capture, #run!] starts each process
+        # @param vault [SecretVault, nil] holds the publish token; one over `commands` when nil
+        def initialize(root:, commands:, vault: nil)
+          @root = root
+          @commands = commands
+          @vault = vault || SecretVault.new(commands: commands)
+        end
+
+        # Says whether npm lists the package at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Hecks::Release::Runner::Refusal] when npm fails for any reason other than the
+        #   version not existing
+        def published?(version)
+          result = @commands.capture("npm", "view", "#{PACKAGE}@#{version}", "version", chdir: @root)
+          return result.stdout.strip == version if result.success?
+          return false if result.stderr.include?("E404")
+
+          raise Release::Runner::Refusal,
+                "could not check npm for #{PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
+                "check the network and re-run"
+        end
+
+        # @return [Boolean] whether the package's dependencies are already installed
+        def installed?
+          Dir.exist?(File.join(package_dir, "node_modules"))
+        end
+
+        # Installs the package's dependencies with `npm ci`.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when it fails
+        def install!
+          @commands.run!("npm", "ci", chdir: package_dir)
+        end
+
+        # Packs the package and publishes nothing.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the pack fails
+        def dry_publish!
+          @commands.run!("npm", "publish", "--dry-run", "--access", "public", chdir: package_dir)
+        end
+
+        # Publishes the package with the token the vault holds.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the publish fails
+        def publish!
+          with_userconfig do |userconfig|
+            @vault.run!(File.join(@root, ENV_FILE), "npm", "publish", "--access", "public", "--auth-type=web",
+                        "--userconfig", userconfig, chdir: package_dir)
+          end
+        end
+
+        private
+
+        def package_dir = File.join(@root, PACKAGE_DIR)
+
+        def with_userconfig
+          file = Tempfile.new(["hecks-npmrc", ".npmrc"])
+          file.chmod(0o600)
+          file.write("#{USERCONFIG_LINE}\n")
+          file.flush
+          yield file.path
+        ensure
+          file&.close!
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/publishing.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "hecks/release/runner"
+require_relative "tree"
+require_relative "gem_registry"
+require_relative "secret_vault"
+require_relative "release_facts"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `PublishingRun` asks of the working tree once the release is cleared:
+      # cutting the release, or pushing the gem alone.
+      #
+      # A release is `Hecks::Release::Runner`: it tags the release commit, publishes the gem and
+      # gets the client package published, skipping what a registry already lists. Its rules were
+      # judged before it starts (the givens of `Clear`), so it is handed the facts they cleared and
+      # checks only that its tools are installed. Unconfirmed it is the dry run: every check and
+      # build, and nothing tagged, pushed or published. The answer says which steps were really
+      # carried out, so the journal can advance the root `Release`: tagged, published, verified.
+      module Publishing
+        # Every operation this family carries out.
+        OPERATIONS = %w[publish publish_gem].freeze
+
+        class << self
+          # @return [#capture, #run!, nil] starts every process a release runs; the real ones
+          #   (`Hecks::Release::Runner::Commands`) when nil. A spec replaces it, so nothing is
+          #   tagged, pushed, published or fetched.
+          attr_accessor :commands
+
+          # @return [Hash] extra arguments for the release, such as `pause:` and `now:`, so a spec
+          #   can wait for the registry without sleeping
+          attr_accessor :release_options
+        end
+
+        module_function
+
+        # The facts of a tree that is not a checkout: placeholders that satisfy the value objects,
+        # so the checkout rule is the one that refuses.
+        #
+        # @param operation [String] `publish` or `publish_gem`
+        # @return [Hash] every fact a release is judged by, none of them true
+        def no_facts(operation)
+          none = { value: "none" }
+          { operation: { value: operation }, version: { value: "0.0.0" }, client_version: { value: "0.0.0" },
+            ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none,
+            tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false } }
+        end
+
+        # Carries out an accepted request.
+        #
+        # @param operation [String] `publish` or `publish_gem`
+        # @param held [Hash] the `PublishingRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused; the release starts its own processes
+        # @return [Hash] `report`, `tagged`, `published` and `verified`, and `version` for the
+        #   `Release` record
+        # @raise [ConsoleCapture::Failure] when the release refuses or a step fails, with its words
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          args = held.transform_values { |value| value.is_a?(Hash) && value.key?(:value) ? value[:value] : value }
+          commands = Publishing.commands || Release::Runner::Commands.new
+          if operation == "publish_gem"
+            publish_gem(args, tree, commands)
+          else
+            publish(args, tree, commands)
+          end
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process
+        # @return [Hash] what the release did
+        # @raise [ConsoleCapture::Failure] when the release stops before any real step; one that
+        #   stops after a real step answers, with `succeeded` false, so the steps are recorded
+        def publish(args, tree, commands)
+          out = StringIO.new
+          err = StringIO.new
+          runner = release(args, tree, commands, out, err)
+          status = runner.call
+          text = [out.string, err.string].map(&:strip).reject(&:empty?).join("\n")
+          raise ConsoleCapture::Failure, text if !status.zero? && runner.steps.empty?
+
+          outcome(text, args, tagged: runner.steps.include?(:tagged), published: runner.steps.include?(:gem),
+                              verified: runner.verified, succeeded: status.zero?)
+        end
+
+        # @return [Hecks::Release::Runner] the release, over the facts the run was cleared by
+        def release(args, tree, commands, out, err)
+          flag = ->(name) { args[name] == true }
+          options = Release::Runner::Options.new(dry_run: args[:confirm] != true, gem_only: flag.call(:gem_only),
+                                                 npm_only: flag.call(:npm_only), npm_local: flag.call(:npm_local),
+                                                 no_wait: flag.call(:no_wait), yes: true)
+          facts = Release::Runner::Preflight::Facts.new(version: args[:version], sha: args[:head])
+          Release::Runner.new(root: tree.root, options: options, commands: commands, input: StringIO.new, out: out,
+                              err: err, facts: facts, **(Publishing.release_options || {}))
+        rescue ArgumentError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # Pushes the gem alone, or builds it and deletes it again when unconfirmed.
+        #
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param commands [#capture, #run!] starts each process
+        # @return [Hash] what was done
+        # @raise [ConsoleCapture::Failure] when the build or the push fails, or the vault is missing
+        def publish_gem(args, tree, commands)
+          registry = GemRegistry.new(root: tree.root, commands: commands)
+          version = args[:version]
+          return dry_gem(registry, version, args) unless args[:confirm] == true
+          raise ConsoleCapture::Failure, "1Password CLI (op) not found; install it: brew install 1password-cli" unless
+            SecretVault.new(commands: commands).installed?
+
+          registry.push!(version)
+          verified = registry.published?(version)
+          outcome("Released hecks #{version}.", args, tagged: false, published: true, verified: verified)
+        rescue Release::Runner::CommandFailed, Release::Runner::Refusal => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @return [Hash] the answer of a gem push that only built the gem
+        def dry_gem(registry, version, args)
+          registry.build_only!(version)
+          outcome("dry run, built hecks-#{version}.gem and deleted it; nothing was pushed (add --confirm)",
+                  args, tagged: false, published: false, verified: false)
+        rescue Release::Runner::CommandFailed => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @return [Hash] the answer the journal records: a report, what was done, and the release
+        def outcome(text, args, tagged:, published:, verified:, succeeded: true)
+          { report: { value: text }, tagged: { value: tagged }, published: { value: published },
+            verified: { value: verified }, succeeded: { value: succeeded }, version: { value: args[:version] },
+            ir_version: { value: args[:ir_version] }, ships_from: args[:ships_from] }
+        end
+      end
+    end
+  end
+end