hecks 3.4.2 → 3.5.0

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

@@ -5,6 +5,8 @@ require_relative "shell"
 require_relative "codebase/tree"
 require_relative "codebase/ruby_child"
 require "hecks/projections/deploy/template_diff"
+require_relative "bluebook_report"
+require_relative "deploy_plans"
 
 module Hecks
   module Adapters
@@ -32,6 +34,55 @@ module Hecks
       SMOKE_STATUS = { 20 => "the roll did not settle", 21 => "gh missing or no repository, smoke not run",
                        22 => "the smoke failed", 23 => "the smoke's result is unknown" }.freeze
 
+      # The file names the AwsBox projection gives the two rolls.
+      SERVICE_SCRIPT = "deploy-service.sh"
+      BOX_SCRIPT = "deploy-box.sh"
+
+      # What each status of `deploy-box.sh` means, for the reason a refusal gives.
+      BOX_STATUS = { 40 => "the box stack has no instance", 41 => "the roll did not succeed on the box",
+                     42 => "the box is not healthy after the roll" }.freeze
+
+      # What each status of `deploy-service.sh` means; it ends with the box roll's own statuses.
+      SERVICE_STATUS = { 2 => "unknown service", 30 => "the existing tag is not in ECR",
+                         31 => "the fresh tag is already in ECR", 32 => "the box's Compose file is unreadable",
+                         33 => "the box stack has no instance", 34 => "the stack has no parameter for the container",
+                         35 => "the stack update failed or did not settle",
+                         36 => "a parameter other than the container's changed",
+                         37 => "the task definition lacks the pushed image",
+                         38 => "the task definition has no such container" }.merge(BOX_STATUS).freeze
+
+      # The file names the AwsBox projection gives the data copy and its comparison.
+      RESTORE_SCRIPT = "restore-to-rds.sh"
+      VERIFY_SCRIPT = "verify-copy.sh"
+
+      # The status `verify-copy.sh` ends with when the databases differ: an answer, not a refusal.
+      DRIFT_STATUS = 50
+
+      # What each status of `restore-to-rds.sh` means, for the reason a refusal gives.
+      RESTORE_STATUS = { 60           => "a Postgres client older than 16",
+                         61           => "the target already has a schema; force=true replaces it",
+                         62           => "unexpected errors restoring a schema",
+                         DRIFT_STATUS => "the copy does not match the source" }.freeze
+
+      # The file name of the bluebook report script and of the preview script; a companion roll runs
+      # `deploy-<companion>.sh`.
+      DIFF_SCRIPT = "bluebooks-diff.sh"
+      PREVIEW_SCRIPT = "preview.sh"
+
+      # What `preview.sh` ends with: every refusal and failure is 1, a bad verb 2.
+      PREVIEW_STATUS = { 1 => "the preview script refused or failed", 2 => "usage" }.freeze
+
+      # What a roll script ends with: every refusal and failed check is 1.
+      COMPANION_STATUS = { 1 => "the roll was refused, did not succeed, or the companion is not healthy" }.freeze
+
+      # The outcome each `preview.sh` verb records; the writes among them need `confirm`.
+      PREVIEW_OUTCOMES = { "name" => "named", "url" => "located", "list" => "listed", "deploy" => "deployed",
+                           "destroy" => "destroyed", "login" => "signed_in" }.freeze
+      PREVIEW_WRITES = %w[deploy destroy login].freeze
+
+      # What `bluebooks-diff.sh` prints when it has nothing to compare.
+      DIFF_UNAVAILABLE = /^==> bluebooks: (could not read|the local domain image has no|the running domain image .* predates)/
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -121,37 +172,267 @@ module Hecks
       # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
       #   non-zero; the message names its status and what it printed
       def smoke(**held)
-        script = smoke_script(plain(held[:project]), plain(held[:script]))
+        run_script(SMOKE_SCRIPT, held, smoke_env(held), "smoke", SMOKE_STATUS)
+      end
+
+      # Rolls one service with a project's generated `deploy-service.sh`, through
+      # `hecks deploy service_roll.run`.
+      #
+      # The script pushes the image under a fresh tag, sets the stack's tag parameter and rolls
+      # the box, so it writes to AWS (a spec puts stand-in programs first on `PATH`).
+      # `SMOKE_BY_COMMAND=1` leaves the smoke to the record's policy; the task definition and
+      # tag come from the script's last line.
+      #
+      # @param held [Hash] the `ServiceRoll` record: `project`, `service`, and `script`,
+      #   `existing_tag` and `local_image` when set
+      # @return [Hash{Symbol => Hash}] `report:`, and `taskdef:` and `tag:` when named
+      # @raise [ConsoleCapture::Failure] when no script is found or it ends non-zero
+      def roll_service(**held)
+        env = { "EXISTING_TAG" => plain(held[:existing_tag]), "LOCAL_IMAGE" => plain(held[:local_image]),
+                "SMOKE_BY_COMMAND" => "1" }.compact
+        answer = run_script(SERVICE_SCRIPT, held, env, "service roll", SERVICE_STATUS, args: [plain(held[:service])])
+        match = answer[:report][:value].match(/^==> rolled taskdef=(\S*) tag=(\S+)$/)
+        answer.merge(taskdef: wrapped(match&.[](1)), tag: wrapped(match&.[](2))).merge(carried(held, "service_roll"))
+      end
+
+      # Rolls the whole box with a project's generated `deploy-box.sh`, through
+      # `hecks deploy box_roll.run`.
+      #
+      # @param held [Hash] the `BoxRoll` record: `project`, and `script`, `taskdef`, `tags` when set
+      # @return [Hash{Symbol => Hash}] `report:` what the script printed
+      # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
+      #   non-zero; the message names its status and what it printed
+      def roll_box(**held)
+        answer = run_script(BOX_SCRIPT, held, {}, "box roll", BOX_STATUS, args: box_args(held))
+        answer.merge(carried(held, "box_roll")).merge(taskdef: wrapped(plain(held[:taskdef])))
+      end
+
+      # Copies a project's schemas into RDS with its generated `restore-to-rds.sh`, through
+      # `hecks deploy data_copy.restore`.
+      #
+      # The script overwrites the target database's schemas, so the adapter refuses unless the
+      # record says `confirm`, naming what would be overwritten. A `dry_run` answers the plan and
+      # runs nothing (confirmed or not). The script runs with `VERIFY_BY_COMMAND=1`: the record's
+      # policy requests the comparison, unless `skip_verify` or a dry run.
+      #
+      # @param held [Hash] the `DataCopy` record
+      # @return [Hash{Symbol => Hash}] `report:`, `planned:` and what the policies carry on
+      # @raise [ConsoleCapture::Failure] when no script is found, the copy is not confirmed, or the
+      #   script ends non-zero
+      def copy_data(**held)
+        script = script_for(RESTORE_SCRIPT, plain(held[:project]), plain(held[:script]))
+        plan = copy_plan(script, held)
+        return copy_answer(held, "#{plan}\ndry run: nothing was run", planned: true) if plain(held[:dry_run]) == true
+
+        unless plain(held[:confirm]) == true
+          raise ConsoleCapture::Failure,
+                "refusing to restore: #{plan}\npass confirm=true to run it (dry_run=true prints this plan)"
+        end
+
+        answer = run_script(RESTORE_SCRIPT, held, copy_env(held), "restore", RESTORE_STATUS, args: copy_args(held))
+        copy_answer(held, answer[:report][:value], planned: false)
+      end
+
+      # Compares two databases with a project's generated `verify-copy.sh`, through
+      # `hecks deploy data_copy.verify`. Read-only on both. Differing databases are an answer
+      # (`drifted:`), not a refusal.
+      #
+      # @param held [Hash] the `CopyVerification` record
+      # @return [Hash{Symbol => Hash}] `report:` and `drifted:`
+      # @raise [ConsoleCapture::Failure] when no script is found or it fails for another reason
+      def compare_copy(**held)
+        env = { "A_DB" => database(held[:source_db]), "B_DB" => database(held[:target_db]) }.compact
+        answer = run_script(VERIFY_SCRIPT, held, env, "verify", {}, args: copy_args(held), answering: [DRIFT_STATUS])
+        { report: answer[:report], drifted: { value: answer.key?(:status) } }
+      end
+
+      # Reports which bluebook releases a deploy changes, through `hecks deploy bluebook_diff.run`.
+      #
+      # With `old` and `new` (two `package.verify` outputs) the comparison is made here, offline.
+      # With neither, the project's `bluebooks-diff.sh` reads the running image's bluebooks
+      # (read-only) and its report is classified. Never a failure: what cannot be compared is
+      # `unavailable`. Only one of `old` and `new` is refused.
+      #
+      # @param held [Hash] the `BluebookDiff` record
+      # @return [Hash{Symbol => Hash}] `outcome:` (unchanged, changed or unavailable) and `report:`
+      # @raise [ConsoleCapture::Failure] when only one of `old` and `new` is given
+      def compare_bluebooks(**held)
+        old = plain(held[:old])
+        new = plain(held[:new])
+        raise ConsoleCapture::Failure, "give old= and new= together, or neither" if old.nil? != new.nil?
+
+        old ? diff_files(old, new) : diff_script(held)
+      end
+
+      # Runs a project's `preview.sh` with one verb, through `hecks deploy preview_run.<verb>`.
+      #
+      # `name`, `url` and `list` read. `deploy`, `destroy` and `login` write to AWS or read its
+      # secrets, so they refuse unless the record says `confirm`, naming the plan; `dry_run` answers
+      # that plan and runs nothing. The branch travels in `BRANCH`, as the script reads it.
+      #
+      # @param held [Hash] the `PreviewRun` record
+      # @return [Hash{Symbol => Hash}] `outcome:`, `report:` and `planned:`
+      # @raise [ConsoleCapture::Failure] when no script is found, a write is not confirmed, or the
+      #   script ends non-zero
+      def run_preview(**held)
+        action = plain(held[:action]).to_s
+        script = script_for(PREVIEW_SCRIPT, plain(held[:project]), plain(held[:script]))
+        if PREVIEW_WRITES.include?(action)
+          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)
+        end
+        env = { "BRANCH" => plain(held[:branch]) }.compact
+        answer = run_script(PREVIEW_SCRIPT, held, env, "preview #{action}", PREVIEW_STATUS, args: [action])
+        { outcome: { value: PREVIEW_OUTCOMES.fetch(action) }, report: answer[:report], planned: { value: false } }
+      end
+
+      # Rolls a companion Compose project onto the box with a project's `deploy-<companion>.sh`,
+      # through `hecks deploy companion_roll.run`.
+      #
+      # The script sends the project and its secret references to the box over SSM and starts it, so
+      # the adapter refuses unless the record says `confirm`, naming the plan; `dry_run` answers the
+      # plan and runs nothing. The task definition is the script's one argument.
+      #
+      # @param held [Hash] the `CompanionRoll` record
+      # @return [Hash{Symbol => Hash}] `report:` and `planned:`
+      # @raise [ConsoleCapture::Failure] when no script is found, the roll is not confirmed, or the
+      #   script ends non-zero
+      def roll_companion(**held)
+        companion = plain(held[:companion]).to_s
+        name = "deploy-#{companion}.sh"
+        script = script_for(name, plain(held[:project]), plain(held[:script]))
+        plan = DeployPlans.companion(File.read(script), companion, plain(held[:taskdef]))
+        return planned_answer(plan) if plain(held[:dry_run]) == true
+
+        require_confirm(held, "roll #{companion}", plan)
+        answer = run_script(name, held, {}, "companion roll", COMPANION_STATUS, args: [plain(held[:taskdef])])
+        answer.merge(planned: { value: false })
+      end
+
+      private
+
+      # 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
 
-        result = Shell.new.capture("bash", script, env: smoke_env(held), chdir: File.dirname(script))
+      # The script reads the registry and the local image; its report says what it found.
+      def diff_script(held)
+        text = run_script(DIFF_SCRIPT, held, {}, "bluebook diff", {}).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(", ")
+        databases = text.match(/^SRC_DB=\$\{SRC_DB:-([^}]*)\}; DST_DB=\$\{DST_DB:-([^}]*)\}/)
+        source_db = database(held[:source_db]) || databases&.[](1)
+        target_db = database(held[:target_db]) || databases&.[](2)
+        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
+
+      # 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
+
+      # Runs one generated script, found for the record's project, from its own directory. Answers
+      # what it printed, or refuses with its status, that status's meaning and its output.
+      def run_script(name, held, env, label, statuses, args: [], answering: [])
+        script = script_for(name, plain(held[:project]), plain(held[:script]))
+        result = Shell.new.capture("bash", script, *args, env: env, chdir: File.dirname(script))
         report = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
         return { report: { value: report } } if result.ok?
 
         code = result.status.exitstatus
-        raise ConsoleCapture::Failure, "smoke ended #{code} (#{SMOKE_STATUS.fetch(code, 'unexpected')})\n#{report}"
-      end
+        return { report: { value: report }, status: code } if answering.include?(code)
 
-      private
+        raise ConsoleCapture::Failure, "#{label} ended #{code} (#{statuses.fetch(code, 'unexpected')})\n#{report}"
+      end
 
-      # The script a project's smoke runs: the override, else `smoke-after-deploy.sh` in the project
-      # itself, else the only one beneath it (not under `node_modules`, `vendor` or `.git`).
-      def smoke_script(project, override)
+      # The script a project runs: the override, else the named one in the project itself, else the
+      # only one beneath it (not under `node_modules`, `vendor` or `.git`).
+      def script_for(name, project, override)
         return existing_script(override) if override
 
         root = File.expand_path(project.to_s)
-        beside = File.join(root, SMOKE_SCRIPT)
+        beside = File.join(root, name)
         return beside if File.file?(beside)
 
-        found = Dir.glob(File.join(root, "**", SMOKE_SCRIPT)).grep_v(%r{/(node_modules|vendor|\.git)/})
+        found = Dir.glob(File.join(root, "**", name)).grep_v(%r{/(node_modules|vendor|\.git)/})
         return found.first if found.one?
 
-        raise ConsoleCapture::Failure, ambiguity(root, found.sort)
+        raise ConsoleCapture::Failure, ambiguity(name, root, found.sort)
       end
 
-      def ambiguity(root, found)
-        return "no #{SMOKE_SCRIPT} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
+      def ambiguity(name, root, found)
+        return "no #{name} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
 
-        "#{found.size} #{SMOKE_SCRIPT} files under #{root}; pass script=<path>: #{found.join(', ')}"
+        "#{found.size} #{name} files under #{root}; pass script=<path>: #{found.join(', ')}"
       end
 
       def existing_script(path)

data/lib/hecks/hecks/adapters/in_process_operations.rb

@@ -23,6 +23,9 @@ module Hecks
       # checkout; an installed gem has none.
       CHECKOUT_MARKER = "hecks.gemspec"
 
+      # The line `hecks model_check` prints before each domain it examines.
+      REPORT_HEADER = /^── /
+
       # Longest a `Follow` query may wait for new entries, so one call cannot hold a launcher open.
       MAX_FOLLOW_WAIT = 60
 
@@ -30,7 +33,8 @@ module Hecks
       #
       # @param held [Hash] the `ModelCheckRun` record: `domains` (comma separated paths), `strict`
       #   and `profile`
-      # @return [Hash{Symbol => Hash}] `report:` the analysis as printed
+      # @return [Hash{Symbol => Hash}] `report:` the analysis as printed, `checked:` how many
+      #   domains it headed
       # @raise [ConsoleCapture::Failure] when a finding was left, or the analysis could not run
       def check(**held)
         argv = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
@@ -43,7 +47,7 @@ module Hecks
         text = ConsoleCapture.answer do
           CLI::ModelCheck.call(argv, program: "hecks model_check", root: checkout_root)
         end
-        { report: { value: text } }
+        { report: { value: text }, checked: { value: text.scan(REPORT_HEADER).size } }
       end
 
       # Dispatches one verb, or executes a step list, against a domain.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -22,7 +22,7 @@ module Hecks
       SCRIPTS = { project: "project_site" }.freeze
 
       # The tool's flag for each `SiteProjection` field that takes a value.
-      FLAGS = { "out" => :out, "template" => :template, "extension" => :extension }.freeze
+      FLAGS = { "out" => :out, "template" => :template, "cms" => :cms, "root" => :root, "extension" => :extension }.freeze
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -33,8 +33,8 @@ module Hecks
 
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
-      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `extension`
-      #   and `check` when set
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `cms`,
+      #   `root`, `extension` and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
       # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
       #   a duplicate path), a path or the extension is refused, or under `check` a file is out

data/lib/hecks/hecks/custodian.bluebook

@@ -121,6 +121,7 @@ Hecks.bluebook "Hecks" do
     attribute :profile, ProfileName, optional: true
     attribute :strict,  Switch,      optional: true
     attribute :report,  Report,      optional: true
+    attribute :checked, Checked,     optional: true
     attribute :refusal, Report,      optional: true
     identified_by :run
 
@@ -146,6 +147,13 @@ Hecks.bluebook "Hecks" do
       attribute :value, String
     end
 
+    # How many domains the report examined, counted from its headers so a reader need not.
+    value_object "Checked" do
+      attribute :value, Integer
+
+      invariant("a count is not negative") { value >= 0 }
+    end
+
     lifecycle :status, default: "requested" do
       transition "Pass" => "clean",   from: "requested"
       transition "Flag" => "flagged", from: "requested"
@@ -173,9 +181,11 @@ Hecks.bluebook "Hecks" do
       goal "Record that the analysis left no error"
 
       reference_to ModelCheckRun
-      attribute :report, Report
+      attribute :report,  Report
+      attribute :checked, Checked
 
       sets :report
+      sets :checked
 
       emits ModelCheckPassed
     end
@@ -214,7 +224,7 @@ Hecks.bluebook "Hecks" do
 
   policy "RecordTheClean" do
     on      "ModelCheckRun.ModelCheckAnswered"
-    trigger ModelCheckRun::Pass, with: { report: :report }
+    trigger ModelCheckRun::Pass, with: { report: :report, checked: :checked }
   end
 
   policy "RecordTheFlag" do

data/lib/hecks/hecks/hecks.hecksagon

@@ -404,11 +404,68 @@ Hecks.hecksagon "Hecks" do
   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/hecks/hecks.world

@@ -40,7 +40,11 @@ Hecks.world "Hecks" do
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
                        settled: %w[package.vendor package.revendor package.release
-                                  operation.bootstrap_admin smoke_run.run],
+                                  operation.bootstrap_admin smoke_run.run
+                                  service_roll.run box_roll.run data_copy.restore
+                                  data_copy.verify bluebook_diff.run preview_run.name
+                                  preview_run.url preview_run.list preview_run.deploy
+                                  preview_run.destroy preview_run.login companion_roll.run],
                        names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
                                 "interview" => "door.interview", "package.check" => "registry.check",
                                 "package.digest" => "registry.digest",

data/lib/hecks/projections/deploy/box/hosting.rb

@@ -33,9 +33,10 @@ module Hecks
           # @param plan [Settings::Plan] the resolved settings
           # @return [String] the Makefile fragment the box `Makefile` includes
           def hosting_mk(plan)
-            Box.template("hosting.mk.tmpl", "SERVICE"      => plan.containers.first.name,
-                                            "URL"          => plan.hosting.public_url.to_s,
-                                            "SMOKE_RECIPE" => Box::SMOKE_RECIPE)
+            Box.template("hosting.mk.tmpl", "SERVICE"        => plan.containers.first.name,
+                                            "URL"            => plan.hosting.public_url.to_s,
+                                            "SMOKE_RECIPE"   => Box::SMOKE_RECIPE,
+                                            "SERVICE_RECIPE" => service_recipe)
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -50,6 +51,14 @@ module Hecks
                          "ROLL_STEPS" => part(roll))
           end
 
+          # @return [String] the `deploy-service` recipe: the `service_roll.run` command
+          def service_recipe
+            args = "service=$(SERVICE) $(if $(EXISTING_TAG),existing_tag=$(EXISTING_TAG)) " \
+                   "$(if $(LOCAL_IMAGE),local_image=$(LOCAL_IMAGE))"
+            direct = "bash ./deploy-service.sh $(SERVICE)"
+            Box::RollRecipe.call(command: "service_roll.run", args: args, direct: direct)
+          end
+
           # @param plan [Settings::Plan] the resolved settings
           # @param region [String] the validated AWS region
           # @return [String] `smoke-after-deploy.sh`
@@ -148,7 +157,7 @@ module Hecks
               resolve_service() {
                 case "$1" in
               #{arms.join("\n")}
-                  *) echo "unknown service '$1', must be one of: ${SERVICES}" >&2; exit 1 ;;
+                  *) echo "unknown service '$1', must be one of: ${SERVICES}" >&2; exit 2 ;;
                 esac
               }
             BASH

data/lib/hecks/projections/deploy/box/roll_recipe.rb

@@ -0,0 +1,62 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The Makefile recipes that run a roll as `box_roll.run` or `service_roll.run`.
+        #
+        # The command rolls with the generated script and, through its policy, requests the
+        # smoke, so one deploy leaves a `BoxRoll` or `ServiceRoll` (which also records the smoke's
+        # outcome) and a `SmokeRun` in the Hecks database. A failed roll or smoke is the command's
+        # exit 1, with the script's status in its message. With no database the command never
+        # starts, so the recipe runs the script itself, states the database error apart from the
+        # deploy's result, and fails (`Error 24` if all passed).
+        module RollRecipe
+          module_function
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the `deploy` target's recipe, tab-indented: the `box_roll.run` command
+          def deploy(plan)
+            variable = plan.task_definition ? "TASKDEF" : "TAGS"
+            args = plan.task_definition ? "$(if $(TASKDEF),taskdef=$(TASKDEF))" : "$(if $(TAGS),tags=\"$(TAGS)\")"
+            direct = "bash ./deploy-box.sh $(#{variable})"
+            direct += " || exit $$?; TASKDEF=\"$(TASKDEF)\" bash ./smoke-after-deploy.sh" if plan.hosting
+            "\t#{call(command: 'box_roll.run', args: args, direct: direct)}"
+          end
+
+          # @param command [String] the Deploy command, such as `box_roll.run`
+          # @param args [String] the Makefile text that turns variables into the arguments
+          # @param direct [String] the shell that runs the script when there is no database
+          # @return [String] the recipe lines, joined for a Makefile rule
+          def call(command:, args:, direct:)
+            [*run_lines(command, args), *no_database_lines(direct), *outcome_lines].join("\n\t").freeze
+          end
+
+          def run_lines(command, args)
+            ["@err=$$(mktemp); run=deploy-$$(date -u +%Y%m%d%H%M%S); \\",
+             "$(HECKS) deploy #{command} project=\"$(CURDIR)\" run=\"$$run\" #{args} \\",
+             '  $(if $(SKIP_POST_DEPLOY_SMOKE),skip_smoke=true) --wait 2>"$$err"; rc=$$?; \\']
+          end
+
+          def no_database_lines(direct)
+            ['if [ $$rc -ne 0 ] && grep -q \'^cannot open Hecks\' "$$err"; then \\',
+             '  echo "==> the deploy record was NOT written: $$(grep -m1 \'^cannot open Hecks\' "$$err")" >&2; \\',
+             '  echo "    one-time setup on this machine: a database AND a non-superuser role that owns it" >&2; \\',
+             '  echo "    (a superuser skips the era write-fence, so createdb alone fails), then set" >&2; \\',
+             '  echo "    HECKS_DATABASE=postgres://<role>@localhost/<db>" >&2; \\',
+             '  echo "    deploying anyway so the deploy is not lost" >&2; \\',
+             "  rm -f \"$$err\"; #{direct}; rc=$$?; \\",
+             '  echo "==> deploy exit $$rc. The deploy record was NOT written: the database is unavailable (see above)." >&2; \\',
+             "  [ $$rc -ne 0 ] || rc=24; exit $$rc; \\",
+             "fi; \\"]
+          end
+
+          def outcome_lines
+            ['cat "$$err" >&2; rm -f "$$err"; exit $$rc']
+          end
+
+          private_class_method :run_lines, :no_database_lines, :outcome_lines
+        end
+      end
+    end
+  end
+end