hecks 3.4.2 → 3.6.0

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

@@ -45,7 +45,7 @@ module Hecks
         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,
+            ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none, release_lane: none,
             tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false } }
         end
 
@@ -80,19 +80,26 @@ module Hecks
           err = StringIO.new
           runner = release(args, tree, commands, out, err)
           status = runner.call
-          text = [out.string, err.string].map(&:strip).reject(&:empty?).join("\n")
+          text = transcript(out, err)
           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?)
+          outcome(text, args, **steps_taken(runner, status))
+        end
+
+        # @return [String] what the release printed to either stream, trimmed
+        def transcript(out, err)
+          [out, err].map { |stream| stream.string.strip }.reject(&:empty?).join("\n")
+        end
+
+        # @return [Hash] which steps the release really carried out, and whether it ended well
+        def steps_taken(runner, status)
+          { 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)
+          options = runner_options(args)
           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 || {}))
@@ -100,6 +107,15 @@ module Hecks
           raise ConsoleCapture::Failure, e.message
         end
 
+        # @return [Hecks::Release::Runner::Options] the release's switches: a dry run unless
+        #   confirmed
+        def runner_options(args)
+          flag = ->(name) { args[name] == true }
+          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)
+        end
+
         # Pushes the gem alone, or builds it and deletes it again when unconfirmed.
         #
         # @param args [Hash] the record's plain fields
@@ -130,11 +146,14 @@ module Hecks
           raise ConsoleCapture::Failure, e.message
         end
 
+        # @param steps [Hash] `tagged`, `published` and `verified`, and `succeeded` (true when
+        #   absent)
         # @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] }
+        def outcome(text, args, **steps)
+          { report: { value: text }, tagged: { value: steps[:tagged] }, published: { value: steps[:published] },
+            verified: { value: steps[:verified] }, succeeded: { value: steps.fetch(:succeeded, true) },
+            version: { value: args[:version] }, ir_version: { value: args[:ir_version] },
+            ships_from: args[:ships_from] }
         end
       end
     end

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

@@ -16,7 +16,7 @@ module Hecks
       # files reports drift and writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus project_ci_gates project_tools_doc decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_lanes project_tools_doc decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -33,13 +33,35 @@ module Hecks
         # @raise [ConsoleCapture::Failure] with the difference, when a check finds drift, or with
         #   what the script printed when it ends badly
         def call(operation, held, tree, shell: nil)
-          flag = ->(name) { (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true }
-          check = flag.call(:check) || !flag.call(:confirm)
+          check = check_only?(held)
           child = RubyChild.new(tree)
-          return project_ci_gates(child, check) if operation == "project_ci_gates"
-          return project_tools_doc(child, check) if operation == "project_tools_doc"
-          return decide_ci_gate(child, held) if operation == "decide_ci_gate"
+          case operation
+          when "project_ci_gates" then project_ci_gates(child, check)
+          when "project_lanes" then project_lanes(child, check, set?(held, :live), set?(held, :confirm))
+          when "project_tools_doc" then project_tools_doc(child, check)
+          when "decide_ci_gate" then decide_ci_gate(child, held)
+          else regenerate(child, check)
+          end
+        end
+
+        # @param held [Hash] the record's fields: `check`, `confirm`
+        # @return [Boolean] whether the run only compares: asked for, or not confirmed
+        def check_only?(held)
+          set?(held, :check) || !set?(held, :confirm)
+        end
 
+        # @param held [Hash] the record's fields
+        # @param name [Symbol] a switch of the record
+        # @return [Boolean] whether the switch was given as true
+        def set?(held, name)
+          (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true
+        end
+
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] how many domains were checked or regenerated
+        # @raise [ConsoleCapture::Failure] with the difference, or with what the script printed
+        def regenerate(child, check)
           result = child.capture("regen_codegen_domains", *("--check" if check))
           raise ConsoleCapture::Failure, refusal(result) unless result.ok?
 
@@ -54,6 +76,21 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # Projects the `Lane` rows, or with `live` compares GitHub's rulesets with them. Only a live
+        # run that is confirmed changes GitHub, so without `confirm` a live run is a comparison.
+        #
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare the files
+        # @param live [Boolean] whether to compare, or with `confirm` update, GitHub's rulesets
+        # @param confirm [Boolean] whether a live run may change GitHub
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale files or differing rulesets
+        def project_lanes(child, check, live, confirm)
+          return child.answer("project_lanes", "--live", *("--confirm" if confirm)) if live
+
+          child.answer("project_lanes", *("--check" if check))
+        end
+
         # @param child [RubyChild] the checkout's tool runner
         # @param check [Boolean] whether to only compare
         # @return [String] what the tool printed

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

@@ -2,6 +2,7 @@
 
 require "json"
 require "hecks/release/runner"
+require "hecks/release/lane"
 require_relative "tree"
 require_relative "../console_capture"
 
@@ -11,7 +12,8 @@ module Hecks
       # The facts a release is judged by, read from git and the checkout's files and judged by
       # nothing here: the rules are the givens of the `Clear` command of `PublishingRun`.
       #
-      # It reads the branch, whether `HEAD` is `origin/main` (after a fetch), whether the tree is
+      # It reads the branch, the lane a release is cut from (the `Lane` row that feeds a tag),
+      # whether `HEAD` is that lane's `origin/` branch (after a fetch), whether the tree is
       # clean, the gem's version and the client package's, whether the changelog has a heading for
       # the version, and where a tag for the version already points. Nothing is changed but the
       # remote-tracking refs a fetch updates.
@@ -49,13 +51,22 @@ module Hecks
         private
 
         def git_facts(version)
+          fetch_origin!
+          head = read("rev-parse", "HEAD")
+          lane_facts(head).merge(clean:     flag(read("status", "--porcelain").empty?),
+                                 tag_state: word(tag_state("v#{version}", head)))
+        end
+
+        def fetch_origin!
           fetch = @git.capture("fetch", "origin")
           raise ConsoleCapture::Failure, "git fetch origin failed (#{fetch.stderr.strip})" unless fetch.success?
+        end
 
-          head = read("rev-parse", "HEAD")
-          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head),
-            on_origin: flag(head == read("rev-parse", "origin/main")),
-            clean: flag(read("status", "--porcelain").empty?), tag_state: word(tag_state("v#{version}", head)) }
+        # Where the checkout stands against the lane a release is cut from.
+        def lane_facts(head)
+          lane = Release::Lane.release
+          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head), release_lane: word(lane),
+            on_origin: flag(head == read("rev-parse", "origin/#{lane}")) }
         end
 
         def tag_state(tag, head)

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

@@ -11,6 +11,7 @@ require_relative "codemods"
 require_relative "test_suite"
 require_relative "corpus_tasks"
 require_relative "publishing"
+require_relative "promotion"
 require_relative "../git"
 
 module Hecks
@@ -47,6 +48,7 @@ module Hecks
       def examine(**held)
         answer = { checkout: { value: tree.checkout? } }
         operation = plain(held[:operation])
+        return answer.merge(promotion_facts(held)) if Codebase::Promotion::OPERATIONS.include?(operation)
         return answer unless Codebase::Publishing::OPERATIONS.include?(operation)
 
         facts = tree.checkout? ? Git.new.survey(**held) : Codebase::Publishing.no_facts(operation)
@@ -180,9 +182,15 @@ module Hecks
       # The task families, each carrying out the operations it lists.
       FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
                   Codebase::Gate, Codebase::Style, Codebase::Codemods, Codebase::TestSuite,
-                  Codebase::CorpusTasks, Codebase::Publishing].freeze
+                  Codebase::CorpusTasks, Codebase::Publishing, Codebase::Promotion].freeze
       private_constant :FAMILIES
 
+      # The facts of a promotion or a watch, naming the operation so policies can tell them apart.
+      def promotion_facts(held)
+        facts = tree.checkout? ? Codebase::Promotion.facts(held, tree) : Codebase::Promotion.no_facts
+        { operation: held[:operation], alert_key: held[:alert_key] }.compact.merge(facts)
+      end
+
       def tree = Codebase::Tree.new
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument

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

@@ -40,7 +40,7 @@ module Hecks
         def regenerate(confirm:)
           return rewrite if confirm
 
-          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(', ')} through the real adapters " \
+          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(", ")} through the real adapters " \
             "(#{installed}; add --confirm)"
         end
 

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

@@ -161,7 +161,7 @@ module Hecks
         # @raise [ConsoleCapture::Failure] when a path begins with `-`
         def after_separator(paths)
           flagged = paths.select { |path| path.start_with?("-") }
-          raise ConsoleCapture::Failure, "paths may not begin with '-': #{flagged.join(', ')}" if flagged.any?
+          raise ConsoleCapture::Failure, "paths may not begin with '-': #{flagged.join(", ")}" if flagged.any?
 
           ["--", *paths]
         end

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

@@ -34,17 +34,23 @@ module Hecks
           path = File.expand_path(file, @tree.root)
           raise ConsoleCapture::Failure, "no such spec file #{file}" unless File.file?(path)
 
+          report = run_example(path, example)
+          raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
+
+          report
+        end
+
+        private
+
+        # What the runner printed for the example, when it passed.
+        def run_example(path, example)
           out = StringIO.new
           status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
-          out.string.strip.tap do |report|
-            raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
-          end
+          out.string.strip
         end
 
-        private
-
         def runner
           return self.class.runner if self.class.runner
 

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

@@ -51,16 +51,35 @@ module Hecks
           case operation
           when "refresh_runtime_baseline" then refresh(args, tree)
           when "run_spec_example" then TestRunner.new(tree).run(file: args[:file], example: args[:example])
-          when "stress_concurrency"
-            answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
-          when "regenerate_legacy_fixtures"
-            SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
-          when "seed_semantics_corpus"
-            answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+          when "stress_concurrency" then stress(args, tree)
+          when "regenerate_legacy_fixtures" then regenerate_fixtures(args, tree, shell)
+          when "seed_semantics_corpus" then seed(args, tree)
           else write_list(args, tree)
           end
         end
 
+        # @param args [Hash] `runs`, `parallel` and `seed_start`
+        # @param tree [Tree] the checkout
+        # @return [String] what the stress run printed
+        def stress(args, tree)
+          answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
+        end
+
+        # @param args [Hash] `confirm`
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] starts the fixtures' child process
+        # @return [String] what was regenerated, or (unconfirmed) what would be
+        def regenerate_fixtures(args, tree, shell)
+          SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
+        end
+
+        # @param args [Hash] `fixture`, perhaps absent
+        # @param tree [Tree] the checkout
+        # @return [String] what the seeding printed
+        def seed(args, tree)
+          answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+        end
+
         # A pure read: a listing, or the recorded pattern cases.
         #
         # @param operation [String] `shard_specs`, `list_io_parallel_specs`, `record_pattern_cases`
@@ -130,8 +149,8 @@ module Hecks
           source = args[:from_run] ? ["--from-run", args[:from_run]] : [*args[:workers]&.to_s]
           return answer { command("refresh_rspec_runtime_baseline").call(source, root: tree.root) } if args[:confirm] == true
 
-          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : 'time a local run'} " \
-            "and rewrite #{BASELINES.join(', ')} (add --confirm)"
+          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : "time a local run"} " \
+            "and rewrite #{BASELINES.join(", ")} (add --confirm)"
         end
 
         # @param args [Hash] `runs`, `parallel` and `seed_start`

data/lib/hecks/hecks/adapters/console_capture.rb

@@ -44,23 +44,27 @@ module Hecks
       #
       # @yield the entry point to run
       # @return [Outcome] the text printed and the exit status
-      def capture
-        synchronize do
-          saved  = [$stdout, $stderr]
-          buffer = StringIO.new
-          begin
-            $stdout = $stderr = buffer
-            status = begin
-              yield
-              0
-            rescue SystemExit => e
-              e.status
-            end
-            Outcome.new(buffer.string, status)
-          ensure
-            $stdout, $stderr = saved
-          end
-        end
+      def capture(&)
+        synchronize { redirected(&) }
+      end
+
+      # Runs the block with both streams pointed at one buffer, putting them back afterwards.
+      def redirected(&)
+        saved  = [$stdout, $stderr]
+        buffer = StringIO.new
+        $stdout = $stderr = buffer
+        status = exit_status(&)
+        Outcome.new(buffer.string, status)
+      ensure
+        $stdout, $stderr = saved
+      end
+
+      # The status the block ends with: 0, or the one an `exit` inside it carries.
+      def exit_status
+        yield
+        0
+      rescue SystemExit => e
+        e.status
       end
 
       # Runs the block captured and answers its text, or refuses with it.

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -78,16 +78,21 @@ module Hecks
 
       # @return [Float] the mean daily total, scaled to an average month
       def monthly_rate(days)
-        mean = days.values.sum { |services| services.values.sum } / days.size
-        mean * DAYS_IN_MONTH
+        mean_daily(days) * DAYS_IN_MONTH
       end
 
+      # @return [Float] the mean daily total across every service
+      def mean_daily(days) = days.values.sum { |services| services.values.sum } / days.size
+
       def report_line(first, last, days, budget)
-        mean = days.values.sum { |services| services.values.sum } / days.size
+        "#{first}..#{last - 1} (#{days.size} days): $#{format("%.2f", mean_daily(days))}/day, " \
+          "$#{format("%.2f", monthly_rate(days))}/month against $#{budget}; biggest: #{biggest_services(days)}"
+      end
+
+      # @return [String] the costliest services, each with its mean daily cost
+      def biggest_services(days)
         biggest = totals_by_service(days).max_by(TOP_SERVICES) { |_name, dollars| dollars }
-        named = biggest.map { |name, dollars| "#{name} $#{format('%.2f', dollars / days.size)}/day" }.join(", ")
-        "#{first}..#{last - 1} (#{days.size} days): $#{format('%.2f', mean)}/day, " \
-          "$#{format('%.2f', monthly_rate(days))}/month against $#{budget}; biggest: #{named}"
+        biggest.map { |name, dollars| "#{name} $#{format("%.2f", dollars / days.size)}/day" }.join(", ")
       end
 
       def totals_by_service(days)

data/lib/hecks/hecks/adapters/deploy_plans.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # The plan a write to AWS prints when it is refused unconfirmed or run with `dry_run`: what the
+    # project's script would do, read from the script's own text, so nothing is run to say it.
+    module DeployPlans
+      module_function
+
+      # What `preview.sh <action>` would do for a branch.
+      #
+      # @param text [String] the preview script's source
+      # @param action [String] `deploy`, `destroy` or `login`
+      # @param branch [String, nil] the branch named, or nil for the checked-out one
+      # @return [String]
+      def preview(text, action, branch)
+        stack = "#{variable(text, "PREFIX") || "<prefix>"}-<name derived from #{branch || "the checked-out branch"}>"
+        region = variable(text, "REGION")
+        where = region ? " in #{region}" : ""
+        case action
+        when "deploy"
+          "push the locally built images and create or update the preview stack #{stack}#{where}, " \
+          "create its database and start its service"
+        when "destroy" then "empty the preview's storage and delete the preview stack #{stack}#{where}"
+        else "read the session secret of the preview stack #{stack}#{where} and mint a signed-in admin session"
+        end
+      end
+
+      # What `deploy-<companion>.sh` would roll, and onto which box.
+      #
+      # @param text [String] the companion script's source
+      # @param companion [String] the companion's name
+      # @param taskdef [String] the task definition its image and settings are read from
+      # @return [String]
+      def companion(text, companion, taskdef)
+        stack = text[/out\s+(\S+)\s+InstanceId/, 1]
+        project = text[/compose -p (\w+)/, 1] || companion
+        directory = text[%r{mkdir -p (/\S+)}, 1]
+        place = directory ? " in #{directory}" : +""
+        "roll #{companion} (Compose project #{project}#{place}) from task definition " \
+          "#{taskdef} onto the box of stack #{stack || "<box stack>"} over SSM, beside the app's project, " \
+          "then check it on the box"
+      end
+
+      # The value a script assigns to an upper-case variable at the start of a line.
+      def variable(text, name) = text[/^#{name}=["']?([^"'\s]+)/, 1]
+    end
+  end
+end

data/lib/hecks/hecks/adapters/deploy_toolchain/answers.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "statuses"
+
+module Hecks
+  module Adapters
+    class DeployToolchain
+      # The answers the asks hand on to the policies that follow them: plans, confirmations, what a
+      # roll or a data copy carries, and the bluebook comparison.
+      module Answers
+        include Statuses
+
+        private
+
+        # Runs the confirmed restore and answers what it printed.
+        def restore(held)
+          script = Scripts::Script.new(RESTORE_SCRIPT, "restore", RESTORE_STATUS, copy_args(held))
+          copy_answer(held, run_script(script, held, copy_env(held))[:report][:value], planned: false)
+        end
+
+        # What a preview verb that writes would do, read from the script, or nil for one that reads.
+        # A dry run answers the plan; otherwise the write needs `confirm`.
+        #
+        # @return [Hash, nil] the dry run's answer, when it is one
+        def gate_preview(held, action)
+          return unless PREVIEW_WRITES.include?(action)
+
+          script = script_for(PREVIEW_SCRIPT, plain(held[:project]), plain(held[:script]))
+          plan = DeployPlans.preview(File.read(script), action, plain(held[:branch]))
+          return planned_answer("#{action}: #{plan}") if plain(held[:dry_run]) == true
+
+          require_confirm(held, "#{action} a preview", plan)
+          nil
+        end
+
+        # What rolling the companion would do, read from its script.
+        def companion_plan(held, name, companion)
+          script = script_for(name, plain(held[:project]), plain(held[:script]))
+          DeployPlans.companion(File.read(script), companion, plain(held[:taskdef]))
+        end
+
+        # A dry run's answer: the plan, and nothing run.
+        def planned_answer(plan)
+          { outcome: { value: "planned" }, report: { value: "#{plan}\ndry run: nothing was run" }, planned: { value: true } }
+        end
+
+        def require_confirm(held, what, plan)
+          return if plain(held[:confirm]) == true
+
+          raise ConsoleCapture::Failure,
+                "refusing to #{what}: #{plan}\npass confirm=true to run it (dry_run=true prints this plan)"
+        end
+
+        def diff_files(old, new)
+          report = BluebookReport.new(File.read(File.expand_path(old)), File.read(File.expand_path(new)))
+          diff_answer(report.changed? ? "changed" : "unchanged", report.text)
+        rescue SystemCallError, JSON::ParserError, TypeError, KeyError => e
+          diff_answer("unavailable", "bluebooks: could not compare #{old} and #{new} (#{e.message.lines.first.strip})")
+        end
+
+        # The script reads the registry and the local image; its report says what it found.
+        def diff_script(held)
+          text = run_script(Scripts::Script.new(DIFF_SCRIPT, "bluebook diff", {}), held, {}).dig(:report, :value)
+          return diff_answer("unavailable", text) if text.match?(DIFF_UNAVAILABLE)
+
+          diff_answer(text.include?("no bluebook changes.") ? "unchanged" : "changed", text)
+        rescue ConsoleCapture::Failure => e
+          diff_answer("unavailable", "bluebooks: #{e.message.lines.first.strip}; nothing to compare.")
+        end
+
+        def diff_answer(outcome, text) = { outcome: { value: outcome }, report: { value: text } }
+
+        # What a data copy's answer hands on to the policies that follow it.
+        def copy_answer(held, report, planned:)
+          carried = %i[project bastion source source_secret target target_secret source_db target_db]
+                    .to_h { |key| [key, { value: plain(held[key]).to_s }] }
+          verify = !planned && plain(held[:skip_verify]) != true
+          carried.merge(report: { value: report }, planned: { value: planned }, run_verify: { value: verify })
+        end
+
+        # A database name the record gave, or nil when it left the script's default.
+        def database(argument) = plain(argument).to_s.empty? ? nil : plain(argument)
+
+        def copy_args(held) = %i[bastion source source_secret target target_secret].map { |key| plain(held[key]) }
+
+        def copy_env(held)
+          { "FORCE" => flag(held[:force]), "SRC_DB" => database(held[:source_db]), "DST_DB" => database(held[:target_db]),
+            "VERIFY_BY_COMMAND" => "1" }.compact
+        end
+
+        # What the script would overwrite, read from the script itself (its schemas and databases).
+        def copy_plan(script, held)
+          text = File.read(script)
+          schemas = text[/^SCHEMAS="([^"]*)"/, 1].to_s.split.join(", ")
+          source_db, target_db = copy_databases(text, held)
+          drop = plain(held[:force]) == true ? "; force=true drops each target schema first" : ""
+          "copy schemas #{schemas} from database #{source_db} on #{plain(held[:source])} into database " \
+            "#{target_db} on #{plain(held[:target])} through bastion #{plain(held[:bastion])}, " \
+            "OVERWRITING those schemas there#{drop}"
+        end
+
+        # The source and target databases: the record's, else the script's defaults.
+        def copy_databases(text, held)
+          databases = text.match(/^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/)
+          [database(held[:source_db]) || databases&.[](1), database(held[:target_db]) || databases&.[](2)]
+        end
+
+        # What a roll's answer hands on to the policies that follow it: the project to find the
+        # smoke in, whether to request the smoke (not when the record opted out or the project has
+        # no smoke script, either of which is noted on the record), and which roll asked.
+        def carried(held, kind)
+          skipped = plain(held[:skip_smoke]) == true
+          script = smoke_script?(plain(held[:project]))
+          note = "smoke skipped: skip_smoke=true" if skipped
+          note ||= "smoke skipped: no smoke script" unless script
+          { project: { value: plain(held[:project]) }, skip_smoke: { value: skipped },
+            run_smoke: { value: note.nil? }, smoke: wrapped(note), kind: { value: kind } }
+        end
+
+        # Whether the project has a generated smoke script the smoke could run.
+        def smoke_script?(project)
+          script_for(SMOKE_SCRIPT, project, nil)
+          true
+        rescue ConsoleCapture::Failure
+          false
+        end
+
+        def wrapped(text) = text.to_s.empty? ? nil : { value: text }
+
+        # What `deploy-box.sh` takes: a task definition, or `name=tag` words.
+        def box_args(held) = [plain(held[:taskdef]), *plain(held[:tags]).to_s.split].compact
+
+        # The taskdef and tag a service roll's last line names.
+        def rolled(text)
+          match = text.match(/^==> rolled taskdef=(\S*) tag=(\S+)$/)
+          { taskdef: wrapped(match&.[](1)), tag: wrapped(match&.[](2)) }
+        end
+      end
+    end
+  end
+end