hecks 3.4.1 → 3.5.0

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -43,6 +43,71 @@ Hecks.hecksagon "Deploy" do
     end
   end
 
+  Deploy::SmokeRun.port "DeployToolchain" do
+    asks "Smoke", to: SmokeRun do
+      attribute :run, RunKey
+      attribute :after, Origin, default: { value: "alone" }
+      answers "SmokeAnswered"
+      refuses "SmokeRefused"
+    end
+  end
+
+  Deploy::ServiceRoll.port "DeployToolchain" do
+    asks "RollService", to: ServiceRoll do
+      attribute :run, RunKey
+      answers "ServiceRollAnswered"
+      refuses "ServiceRollRefused"
+    end
+  end
+
+  Deploy::BoxRoll.port "DeployToolchain" do
+    asks "RollBox", to: BoxRoll do
+      attribute :run, RunKey
+      answers "BoxRollAnswered"
+      refuses "BoxRollRefused"
+    end
+  end
+
+  Deploy::DataCopy.port "DeployToolchain" do
+    asks "CopyData", to: DataCopy do
+      attribute :run, RunKey
+      answers "DataCopyAnswered"
+      refuses "DataCopyRefused"
+    end
+  end
+
+  Deploy::CopyVerification.port "DeployToolchain" do
+    asks "CompareCopy", to: CopyVerification do
+      attribute :run, RunKey
+      answers "CopyVerificationAnswered"
+      refuses "CopyVerificationRefused"
+    end
+  end
+
+  Deploy::BluebookDiff.port "DeployToolchain" do
+    asks "CompareBluebooks", to: BluebookDiff do
+      attribute :run, RunKey
+      answers "BluebookDiffAnswered"
+      refuses "BluebookDiffRefused"
+    end
+  end
+
+  Deploy::PreviewRun.port "DeployToolchain" do
+    asks "RunPreview", to: PreviewRun do
+      attribute :run, RunKey
+      answers "PreviewRunAnswered"
+      refuses "PreviewRunRefused"
+    end
+  end
+
+  Deploy::CompanionRoll.port "DeployToolchain" do
+    asks "RollCompanion", to: CompanionRoll do
+      attribute :run, RunKey
+      answers "CompanionRollAnswered"
+      refuses "CompanionRollRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/deploy/oidc.json

@@ -1,11 +1,101 @@
 {
   "audience": "Deploy",
   "scopes": [
+    {
+      "scope": "deploy:bluebook_diff.differ",
+      "verb": "Deploy::BluebookDiff.Differ",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.flag",
+      "verb": "Deploy::BluebookDiff.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.match",
+      "verb": "Deploy::BluebookDiff.Match",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.run",
+      "verb": "Deploy::BluebookDiff.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.withhold",
+      "verb": "Deploy::BluebookDiff.Withhold",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.complete",
+      "verb": "Deploy::BoxRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.flag",
+      "verb": "Deploy::BoxRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.flag_smoke",
+      "verb": "Deploy::BoxRoll.FlagSmoke",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.run",
+      "verb": "Deploy::BoxRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.verify",
+      "verb": "Deploy::BoxRoll.Verify",
+      "role": null
+    },
     {
       "scope": "deploy:box_target.declare",
       "verb": "Deploy::BoxTarget.Declare",
       "role": null
     },
+    {
+      "scope": "deploy:companion_roll.complete",
+      "verb": "Deploy::CompanionRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.flag",
+      "verb": "Deploy::CompanionRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.plan",
+      "verb": "Deploy::CompanionRoll.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.run",
+      "verb": "Deploy::CompanionRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.differ",
+      "verb": "Deploy::CopyVerification.Differ",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.flag",
+      "verb": "Deploy::CopyVerification.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.match",
+      "verb": "Deploy::CopyVerification.Match",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.run",
+      "verb": "Deploy::CopyVerification.Run",
+      "role": null
+    },
     {
       "scope": "deploy:cost_check.check",
       "verb": "Deploy::CostCheck.Check",
@@ -21,6 +111,46 @@
       "verb": "Deploy::CostCheck.Pass",
       "role": null
     },
+    {
+      "scope": "deploy:data_copy.complete",
+      "verb": "Deploy::DataCopy.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.confirm",
+      "verb": "Deploy::DataCopy.Confirm",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.drift",
+      "verb": "Deploy::DataCopy.Drift",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.flag",
+      "verb": "Deploy::DataCopy.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.flag_verification",
+      "verb": "Deploy::DataCopy.FlagVerification",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.plan",
+      "verb": "Deploy::DataCopy.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.restore",
+      "verb": "Deploy::DataCopy.Restore",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.verify",
+      "verb": "Deploy::DataCopy.Verify",
+      "role": null
+    },
     {
       "scope": "deploy:fargate_target.declare",
       "verb": "Deploy::FargateTarget.Declare",
@@ -61,6 +191,76 @@
       "verb": "Deploy::OidcManifest.ProjectOidc",
       "role": null
     },
+    {
+      "scope": "deploy:preview_run.deploy",
+      "verb": "Deploy::PreviewRun.Deploy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.destroy",
+      "verb": "Deploy::PreviewRun.Destroy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.flag",
+      "verb": "Deploy::PreviewRun.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.list",
+      "verb": "Deploy::PreviewRun.List",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.login",
+      "verb": "Deploy::PreviewRun.Login",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.name",
+      "verb": "Deploy::PreviewRun.Name",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.plan",
+      "verb": "Deploy::PreviewRun.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_deploy",
+      "verb": "Deploy::PreviewRun.RecordDeploy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_destroy",
+      "verb": "Deploy::PreviewRun.RecordDestroy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_list",
+      "verb": "Deploy::PreviewRun.RecordList",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_login",
+      "verb": "Deploy::PreviewRun.RecordLogin",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_name",
+      "verb": "Deploy::PreviewRun.RecordName",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_url",
+      "verb": "Deploy::PreviewRun.RecordUrl",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.url",
+      "verb": "Deploy::PreviewRun.Url",
+      "role": null
+    },
     {
       "scope": "deploy:recipe.complete",
       "verb": "Deploy::Recipe.Complete",
@@ -76,6 +276,46 @@
       "verb": "Deploy::Recipe.Project",
       "role": null
     },
+    {
+      "scope": "deploy:service_roll.complete",
+      "verb": "Deploy::ServiceRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.flag",
+      "verb": "Deploy::ServiceRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.flag_smoke",
+      "verb": "Deploy::ServiceRoll.FlagSmoke",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.run",
+      "verb": "Deploy::ServiceRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.verify",
+      "verb": "Deploy::ServiceRoll.Verify",
+      "role": null
+    },
+    {
+      "scope": "deploy:smoke_run.flag",
+      "verb": "Deploy::SmokeRun.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:smoke_run.pass",
+      "verb": "Deploy::SmokeRun.Pass",
+      "role": null
+    },
+    {
+      "scope": "deploy:smoke_run.run",
+      "verb": "Deploy::SmokeRun.Run",
+      "role": null
+    },
     {
       "scope": "deploy:template_comparison.diff",
       "verb": "Deploy::TemplateComparison.Diff",

data/lib/hecks/doors/cli_runner.rb

@@ -251,13 +251,22 @@ module Hecks
         events    = runtime.events.select { |event| event.aggregate == fqn && event.id == handle.id }
         answer    = { id: handle.id, state: JsonDoor.materialize(state),
                       events: (events.empty? ? handle.events : events).map(&:name) }.merge(extra)
-        if LauncherOptions.failed?(aggregate, state, launcher)
-          field = aggregate.lifecycle.field
-          why  += [failure_sentence(aggregate, state, field)]
-        end
+        failed = LauncherOptions.failed?(aggregate, state, launcher)
+        why += [failure_sentence(aggregate, state, aggregate.lifecycle.field)] if failed
+        return report_of(answer[:state], why) if LauncherOptions.report?(launcher, spec)
+
         finish(JSON.pretty_generate(answer), why)
       end
 
+      # The answer of a command the launcher prints as its report: the text it recorded, with
+      # the status 1 when the run failed, and nothing else.
+      def report_of(state, why)
+        text = state[why.empty? ? :output : :refusal]
+        text = text[:value] if text.is_a?(Hash)
+        text = why.join("\n") if text.to_s.strip.empty?
+        [text.to_s, why.empty? ? 0 : 1]
+      end
+
       # The sentence for a record that ended in a failure state: the state, then the record's own
       # `refusal` when it keeps one, without the class name an adapter's failure carries.
       def failure_sentence(aggregate, state, field)

data/lib/hecks/doors/launcher_options.rb

@@ -12,8 +12,9 @@ module Hecks
     #
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
-    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait` was
-    #   given, so a script gets their outcome in its exit status.
+    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait`
+    #   was given, so a script gets their outcome in its exit status.
+    # - **report** lists the settled commands whose answer is the report they recorded, as text.
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
     # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
     module LauncherOptions
@@ -97,6 +98,17 @@ module Hecks
         Array(launcher[:settled]).map(&:to_s).include?(spec[:short].to_s)
       end
 
+      # Whether a command prints the report it recorded instead of its whole record.
+      #
+      # @param launcher [Hash, nil] the chapter's `launcher` setting
+      # @param spec [Hash] the command's projected spec
+      # @return [Boolean] true for a command the setting lists under `report`
+      def report?(launcher, spec)
+        return false unless launcher && spec[:kind] == :command
+
+        Array(launcher[:report]).map(&:to_s).include?(spec[:short].to_s)
+      end
+
       # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists it
       # under `streams`, by the question's own name.
       #

data/lib/hecks/hecks/adapters/bluebook_report.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    # Which bluebook releases one deploy changes: two `hecks package.verify` outputs compared by
+    # bluebook name, version, shape and digest.
+    #
+    # A bluebook is added, removed, re-versioned (a new era when its shape changed too), or has the
+    # same version with different content (a vendored copy edited or re-tagged). The comparison is
+    # pure; reading the running image's label out of a registry is not done here.
+    class BluebookReport
+      ROW = "    %-24s %s"
+
+      # @param old_json [String] the running side's `package.verify` output
+      # @param new_json [String] the side about to ship
+      # @param label [String] what the old side is called in the heading
+      # @raise [JSON::ParserError] when either side is not JSON
+      def initialize(old_json, new_json, label: "old")
+        @old = JSON.parse(old_json)
+        @new = JSON.parse(new_json)
+        @label = label
+        @changed = false
+        @era = false
+      end
+
+      # @return [Boolean] whether any bluebook was added, removed, re-versioned or changed
+      def changed?
+        text
+        @changed
+      end
+
+      # @return [String] the heading, one line per bluebook, the commits, and a note on a new era
+      def text
+        @text ||= build.join("\n")
+      end
+
+      private
+
+      def build
+        old_books = @old.fetch("bluebooks", {})
+        new_books = @new.fetch("bluebooks", {})
+        lines = ["==> bluebooks in this deploy (#{@label} -> this build)"]
+        (old_books.keys | new_books.keys).sort.each { |name| lines << row(name, old_books[name], new_books[name]) }
+        lines << commits
+        lines << "    no bluebook changes." unless @changed
+        lines << "    NOTE: a shape change mints a new era when the domain boots on it." if @era
+        lines
+      end
+
+      def row(name, old, new)
+        return mark(name, "ADDED #{new['version']}") if old.nil?
+        return mark(name, "REMOVED (was #{old['version']})") if new.nil?
+        return reversioned(name, old, new) if old["version"] != new["version"]
+        return same_version_changed(name, old, new) if old["digest"] != new["digest"]
+
+        format(ROW, name, "#{new['version']}   unchanged")
+      end
+
+      def same_version_changed(name, old, new)
+        mark(name, "#{new['version']}   SAME VERSION, DIFFERENT CONTENT (digest #{old['digest'][0, 8]} -> " \
+                   "#{new['digest'][0, 8]}); a vendored copy was edited or re-tagged")
+      end
+
+      def reversioned(name, old, new)
+        line = "#{old['version']} -> #{new['version']}"
+        if old["shape"] != new["shape"]
+          line += "   shape #{shape(old)} -> #{shape(new)}   NEW ERA (its translation edge must already be in " \
+                  "bluebook/translations/)"
+          @era = true
+        end
+        mark(name, line)
+      end
+
+      def mark(name, text)
+        @changed = true
+        format(ROW, name, text)
+      end
+
+      def shape(book) = book["shape"].map { |entry| entry.split.last }.join(", ")
+
+      def commits
+        old = @old.dig("built_from", "commit") || "?"
+        new = @new.dig("built_from", "commit") || "?"
+        dirty = @new.dig("built_from", "dirty") ? " (uncommitted changes)" : ""
+        "    built from #{old[0, 7]} -> #{new[0, 7]}#{dirty}"
+      end
+    end
+  end
+end

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}" : String.new
+        "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