hecks 2.9.0 → 3.0.0

data/lib/hecks/cli/model_check.rb

@@ -3,7 +3,7 @@ require_relative "../bluebook/model_check"
 
 module Hecks
   module CLI
-    # The command behind `bin/model_check` and `hecks model_check`: static analysis
+    # The command behind `hecks model_check`: static analysis
     # over the IR, printed per domain, exiting non-zero when any error-severity
     # finding is left — unreachable lifecycle states, dead transitions, unreached
     # saga states, dispatches to a nonexistent command, handlers for an event
@@ -24,7 +24,8 @@ module Hecks
 
       # Runs the model check `argv` describes and exits with its verdict.
       #
-      # @param argv [Array<String>] `--strict`, `--profile NAME` and domain paths
+      # @param argv [Array<String>] `--strict`, `--profile NAME`, `--wait` and domain paths;
+      #   `--wait` is accepted for the launcher's sake, as the verdict is always the exit status
       # @param program [String] the name the usage message calls this command by
       # @param root [String, nil] the repository root, for the corpus sweep and the
       #   Rust-target check; nil when there is no checkout
@@ -34,6 +35,7 @@ module Hecks
       def call(argv, program:, root: nil)
         argv = argv.dup
         strict = !argv.delete("--strict").nil?
+        argv.delete("--wait")
         profile = take_profile(argv)
         unless profile.nil? || Bluebook::ModelCheck::PROFILES.include?(profile)
           warn "unknown profile #{profile.inspect} (known: #{Bluebook::ModelCheck::PROFILES.join(', ')})"
@@ -105,11 +107,12 @@ module Hecks
 
         # A port attaches to its aggregate from the hecksagon, not the bluebook, so a
         # deaf-policy check that skipped it would miss a policy reacting to an event
-        # nothing emits. Recording a bind builds IR only; no adapter resolves here.
+        # nothing emits. Recording a bind builds IR only; no adapter resolves here. A chapter
+        # that ships its ports beside its bluebook (`<name>.ports.hecksagon`) is read with them.
         hecksagons = if File.directory?(source)
                        Dir.glob(File.join(source, "*.hecksagon"))
                      else
-                       [source.sub(/\.bluebook\z/, ".hecksagon")]
+                       [".hecksagon", ".ports.hecksagon"].map { |suffix| source.sub(/\.bluebook\z/, suffix) }
                      end
         hecksagons.each { |hecksagon| Kernel.load(hecksagon) if File.exist?(hecksagon) }
       end

data/lib/hecks/cli/pattern_cases.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module CLI
+    # The command behind `hecks record_pattern_cases`: records the expected match results for
+    # `pattern:` cases, which `spec/pattern_subset_spec.rb` reads from
+    # `spec/corpus/fixtures/patterns.json`.
+    #
+    # The inputs cover embedded and trailing newlines and non-ASCII digits and word characters.
+    module PatternCases
+      # Each pattern with the inputs it is matched against.
+      CASES = [
+        ["^[A-Z]{3}-[0-9]{4}$", ["ABC-1234", "abc-1234", "xx\nABC-1234\nyy", "ABC-1234\n", "ABC-١٢٣٤"]],
+        ["^[0-9]{5}(-[0-9]{4})?$", ["12345", "12345-6789", "1234", "12345\nx", "١٢٣٤٥"]],
+        ['^[^@ ]+@[^@ ]+\.[^@ ]+$', ["a@b.co", "a b@c.co", "no-at-sign", "a@b.co\nevil", "\na@b.co", "café@x.co"]],
+        ["^(red|green|blue)$", ["red", "purple", "red\ngreen", "RED", "x\nred"]],
+        ["^[A-Za-z0-9_]+$", ["abc_1", "a b", "café", "abc\ndef"]],
+        ['^[ \t]*$', ["", "   ", " ", "a", "\n", "\t"]],
+        ["^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$", ["12345678-1234-1234-1234-123456789abc", "nope"]],
+        ['^\+?[0-9 ()-]{7,20}$', ["+44 20 1234", "abc", "+44 20 1234\nx"]],
+        ['\Aonly\z', ["only", "only\n", "x\nonly"]],
+        ["^a.c$", ["abc", "a\nc", "a\tc", "aéc"]]
+      ].freeze
+
+      module_function
+
+      # @return [Array<Hash{String => Object}>] one row per pattern and input, with its match result
+      def rows
+        CASES.flat_map do |pattern, inputs|
+          regexp = Regexp.new(pattern)
+          inputs.map { |input| { "pattern" => pattern, "input" => input, "matches" => regexp.match?(input) } }
+        end
+      end
+
+      # Prints the rows as pretty JSON.
+      #
+      # @param out [IO] where the JSON goes
+      # @return [Integer] the exit status, always 0
+      def call(out: $stdout)
+        out.puts JSON.pretty_generate(rows)
+        0
+      end
+    end
+  end
+end

data/lib/hecks/cli/present.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../forms"
+require_relative "../forms/banking_presentation"
+
+module Hecks
+  module CLI
+    # The command behind `hecks present` and `hecks present`: serves the banking example's rendered
+    # forms and views, backed by the in-memory adapter
+    # (docs/command-form-and-query-form-bluebook.md).
+    #
+    # Then, for example, `http://localhost:4567/` lists every exposed chapter,
+    # `/Banking/Customer.html` every Customer plus Register, `/Banking/Account/Overdrawn.html` a
+    # query view, and `/Banking/Account/Debit` answers the command's shape as JSON.
+    module Present
+      ROOT = File.expand_path("../../..", __dir__)
+
+      module_function
+
+      # Starts a development server and blocks until it stops.
+      #
+      # @param argv [Array<String>] `[-p port]`
+      # @param program [String] the name the refusal calls this command by
+      # @param root [String] the checkout whose examples are served
+      # @return [void]
+      # @raise [SystemExit] when the port argument is refused
+      def call(argv, program: "hecks present", root: ROOT)
+        require "rackup"
+        port, error = Hecks::Forms::PortArgument.parse(argv)
+        abort "#{program}: #{error}" if error
+
+        app = Hecks::Forms::BankingPresentation.app(root: root)
+        puts "command_form.bluebook/query_form.bluebook — Banking, in memory — http://localhost:#{port}/"
+        puts "development server: no authentication, no CSRF protection, no caller identity — do not expose beyond localhost"
+        Rackup::Server.start(app: app, Port: port, server: "webrick")
+      end
+    end
+  end
+end

data/lib/hecks/cli/project_cli.rb

@@ -3,35 +3,133 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/project_cli` and `hecks project_cli`: writes a
+    # The command behind `hecks project_cli` and `hecks project_cli`: writes a
     # command-line launcher beside each domain, named after its bluebook, so
     # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
     #
     # Each launcher is a dozen lines pinning one directory and handing over to
-    # `Facade::CliRunner`; the surface itself is projected at the moment it runs,
+    # `Doors::CliRunner`; the surface itself is projected at the moment it runs,
     # so editing a chapter changes behaviour without regenerating anything.
+    #
+    # A chapter whose world's `launcher` setting names an `executable` gets its launcher
+    # there instead: the Hecks chapter's is the gem's `exe/hecks`.
     module ProjectCli
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
+      # What a chapter name, a domain path and a launcher verb may be made of.
+      NAME = /\A[A-Za-z][A-Za-z0-9_ ]*\z/
+      PATH = %r{\A[\w./-]+\z}
+      VERB = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+      # Set first in an opted-in launcher, before anything reads a file.
+      ENCODING = "Encoding.default_external = Encoding::UTF_8\nEncoding.default_internal = Encoding::UTF_8\n\n".freeze
+
+      # How every launcher ends.
+      PLAIN_ENDING = "status.zero? ? puts(text) : abort(text)".freeze
+
+      # How an opted-in launcher ends: a failed `--wait` run still prints its settled record.
+      OPTED_ENDING = <<~LAUNCHER_TAIL.chomp.freeze
+        # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
+        # either way, and says why on stderr.
+        if reason
+          puts text
+          warn reason
+          exit status
+        end
+        status.zero? ? puts(text) : abort(text)
+      LAUNCHER_TAIL
+
+      # The generator's name as an executable launcher's header states it, whoever ran it.
+      GENERATOR = "hecks project_cli".freeze
+
       module_function
 
-      # `remove_stale_bin` deletes `root/bin/<name>`, where a launcher for the same
-      # chapter would otherwise linger as a second front door.
+      # Writes a launcher for each named domain, or for every domain under `root`.
+      #
+      # `--check` writes nothing and exits 1 when a launcher differs from the one this would
+      # write. A domain that cannot boot has none to compare, so it fails too.
+      #
+      # @param argv [Array<String>] domain paths under `root`, and optionally `--check`
+      # @param program [String] how the caller was invoked, named in a launcher's header
+      # @param root [String] the directory launchers are written under
+      # @param remove_stale_bin [Boolean] delete `root/bin/<name>`, a second front door
+      # @return [void]
+      # @raise [SystemExit] with status 1 for a launcher out of date, an unreadable domain, a
+      #   path outside `root` or an unknown flag
       def call(argv, program:, root:, remove_stale_bin: true)
-        wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
+        flags, paths = argv.partition { |word| word.start_with?("-") }
+        unknown = flags - ["--check"]
+        abort "hecks project_cli: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
 
-        wanted.each do |path|
-          name  = bluebook_name(root, path) or next
-          snake = Naming.snake(name)
-          file  = File.join(root, path, snake)
+        check  = flags.include?("--check")
+        wanted = paths.empty? ? domains(root) : paths.map { |path| under_root(root, path) }
 
-          File.write(file, launcher(path, name, program))
-          FileUtils.chmod("+x", file)
-          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin
+        outcomes = wanted.to_h { |path| [path, one(root, path, program, check, remove_stale_bin)] }
+        drifted  = outcomes.select { |_, outcome| outcome == :drifted }.keys
+        failed   = outcomes.select { |_, outcome| outcome == :failed }.keys
+        return if drifted.empty? && failed.empty?
+
+        warn "launcher out of date for: #{drifted.join(', ')}; run `hecks project_cli #{drifted.join(' ')}`" unless drifted.empty?
+        warn "no launcher could be checked or written for: #{failed.join(', ')}" unless failed.empty?
+        exit 1
+      end
+
+      # A domain path as a path under `root`.
+      #
+      # @param root [String] the directory launchers are written under
+      # @param path [String] the path as typed, relative to `root` or absolute
+      # @return [String] the path relative to `root`
+      # @raise [SystemExit] when the path is outside `root`
+      def under_root(root, path)
+        expanded = File.expand_path(path, root)
+        inside   = expanded == root || expanded.start_with?("#{root}/")
+        abort "hecks project_cli: #{path.inspect} is outside #{root}" unless inside
+
+        relative = expanded.delete_prefix(root).delete_prefix("/")
+        relative.empty? ? "." : relative
+      end
+
+      # @api private
+      # @return [Symbol] `:current` when the launcher is (or was made) as generated, `:drifted`
+      #   when `check` found it out of date, `:failed` when the domain could not be read or its
+      #   launcher could not be made
+      def one(root, path, program, check, remove_stale_bin)
+        runtime = Hecks.boot(File.join(root, path), install_doors: false)
+        name    = runtime.registry.bluebooks.keys.first or raise "it loads no bluebook"
+        setting    = Doors::LauncherOptions.settings(runtime, name) || {}
+        snake      = Naming.snake(name)
+        executable = setting[:executable]
+        label      = executable || "#{path}/#{snake}"
+        file       = File.join(root, label)
+        text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
+                          opted: !setting.empty?)
+        return skip(path, "#{label} is a directory") if File.directory?(file)
 
-          puts "  #{path}/#{snake}  ->  #{name}"
+        return :drifted if check && !(File.file?(file) && File.read(file) == text)
+
+        unless check
+          File.write(file, text)
+          FileUtils.chmod("+x", file)
+          FileUtils.rm_f(File.join(root, "bin", snake)) if remove_stale_bin && !executable
         end
+        puts "  #{label}  ->  #{name}"
+        :current
+      rescue StandardError => e
+        refuse(path, "cannot boot — #{e.message.lines.first.to_s.strip}")
+      end
+
+      # @api private
+      # @return [Symbol] `:current`: a directory where the launcher would go has nothing to check
+      def skip(path, reason)
+        warn "  #{path}: #{reason}; no launcher written"
+        :current
+      end
+
+      # @api private
+      def refuse(path, reason)
+        warn "  #{path}: #{reason}"
+        :failed
       end
 
       def domains(root)
@@ -44,18 +142,41 @@ module Hecks
            .uniq.sort
       end
 
-      # Reads the name from `Hecks.bluebook "…"` rather than the directory, so a
-      # domain using `formerly_known_as` gets a launcher under its current name.
-      def bluebook_name(root, path)
-        Hecks.boot(File.join(root, path), install_facade: false).registry.bluebooks.keys.first
-      rescue StandardError => e
-        warn "  #{path}: cannot boot — #{e.message.lines.first.strip}"
-        nil
-      end
-
-      def launcher(path, name, program)
+      # The source of one launcher; names and paths go in as they are, so each must be plain.
+      # An `opted` one also sets UTF-8 and prints a failed `--wait` record on stdout.
+      # @param path [String] the domain's directory under the root
+      # @param name [String] the chapter's name
+      # @param program [String] the generator's invocation, named in the header
+      # @param executable [String, nil] the file's path under the root when it is not beside the
+      #   domain; its program name is then that file's basename, and its header names the generator
+      # @param legacy [Array<String>, nil] verbs an executable hands to `Hecks::CLI` first
+      # @param opted [Boolean] whether the chapter's world declares a `launcher` setting
+      # @return [String] the Ruby source
+      # @raise [ArgumentError] if a name, path, executable or legacy verb is not plain
+      def launcher(path, name, program, executable: nil, legacy: nil, opted: !executable.nil?)
+        plain!("chapter name", name, NAME)
+        plain!("domain path", path, PATH)
         snake = Naming.snake(name)
-        up    = "../" * path.count("/").succ
+        if executable
+          plain!("launcher executable", executable, PATH)
+          if executable.split("/").include?("..")
+            raise ArgumentError, "launcher executable #{executable.inspect} must stay inside the root"
+          end
+
+          up      = "../" * File.dirname(executable).split("/").reject { |part| part == "." }.length
+          boot    = %(File.expand_path("#{up}#{path}", __dir__))
+          program = GENERATOR
+          where   = executable
+          shown   = File.basename(executable)
+        else
+          up    = "../" * path.count("/").succ
+          boot  = "__dir__"
+          where = shown = "#{path}/#{snake}"
+        end
+
+        handoff  = legacy_handoff(Array(legacy)) if executable
+        encoding = opted ? ENCODING : ""
+        ending   = opted ? OPTED_ENDING : PLAIN_ENDING
 
         <<~RUBY
           #!/usr/bin/env ruby
@@ -66,23 +187,94 @@ module Hecks
           # projected from the bluebook beside it every time this runs, so a change
           # to the chapter shows up here without re-minting anything.
           #
-          #   #{path}/#{snake}                  every verb, and every question
-          #   #{path}/#{snake} <verb> --help    what it wants, and how it refuses
-
-          $LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+          #   #{where}                  every verb, and every question
+          #   #{where} <verb> --help    what it wants, and how it refuses
 
+          #{encoding}$LOAD_PATH.unshift File.expand_path("#{up}lib", __dir__)
+          #{handoff}
           require "hecks"
 
+          #{entry(name, boot, shown, opted)}
+          #{ending}
+        RUBY
+      end
+
+      # @api private
+      # @return [String] the launcher's middle: for an opted-in launcher, usage answered from the
+      #   projection and a boot only for a line that runs a verb; for any other, the boot and
+      #   dispatch every launcher has always had, byte for byte
+      def entry(name, boot, shown, opted)
+        opted ? described_entry(name, boot, shown) : plain_entry(name, boot, shown)
+      end
+
+      # @api private
+      # @return [String] the opted-in launcher's middle
+      def described_entry(name, boot, shown)
+        <<~RUBY.chomp
+          # Usage is answered from the projected chapter alone: no adapter is bound and no
+          # database is opened. Only a line that runs a verb boots the domain.
+          domain = #{boot}
+          program = "#{shown}"
+          described = begin
+            Hecks.describe(domain)
+          rescue StandardError => e
+            abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+          end
+
+          text, status, reason = Hecks::Doors::CliRunner.usage(
+            runtime: described, argv: ARGV, program: program
+          )
+          unless text
+            runtime = begin
+              Hecks.boot(domain, install_doors: false)
+            rescue StandardError => e
+              abort "cannot open #{name}: \#{e.message.lines.first.strip}"
+            end
+            text, status, reason = Hecks::Doors::CliRunner.call(
+              runtime: runtime, argv: ARGV, program: program
+            )
+          end
+        RUBY
+      end
+
+      # @api private
+      # @return [String] the middle every launcher had before opted-in ones answered usage alone
+      def plain_entry(name, boot, shown)
+        <<~RUBY.chomp
           runtime = begin
-            Hecks.boot(__dir__, install_facade: false)
+            Hecks.boot(#{boot}, install_doors: false)
           rescue StandardError => e
             abort "cannot open #{name}: \#{e.message.lines.first.strip}"
           end
 
-          text, status = Hecks::Facade::CliRunner.call(
-            runtime: runtime, argv: ARGV, program: "#{path}/#{snake}"
+          text, status = Hecks::Doors::CliRunner.call(
+            runtime: runtime, argv: ARGV, program: "#{shown}"
           )
-          status.zero? ? puts(text) : abort(text)
+        RUBY
+      end
+
+      # @api private
+      def plain!(what, value, pattern)
+        return if value.to_s.match?(pattern)
+
+        raise ArgumentError, "#{what} #{value.to_s.inspect} is not a plain word or path"
+      end
+
+      # @api private
+      # @return [String] the lines that hand the legacy verbs to `Hecks::CLI`, or nothing
+      def legacy_handoff(legacy)
+        return "" if legacy.empty?
+
+        legacy.each { |verb| plain!("legacy verb", verb, VERB) }
+
+        <<~RUBY
+
+          # The names the gem has always shipped keep their positional forms.
+          LEGACY = %w[#{legacy.join(' ')}].freeze
+          if LEGACY.include?(ARGV.first)
+            require "hecks/cli"
+            exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+          end
         RUBY
       end
     end

data/lib/hecks/cli/project_diagrams.rb

@@ -2,10 +2,11 @@ require_relative "../../hecks"
 
 module Hecks
   module CLI
-    # The command behind `bin/project_diagrams` and `hecks project_diagrams`: boots a
+    # The command behind `hecks project_diagrams`: boots a
     # domain, finds the chapter it names, and writes its Mermaid diagrams
     # (`Projections::Diagrams`) under `docs/generated/diagrams/<chapter>/` below the
-    # root.
+    # root. Only this positional form writes; the launcher's `domain=… chapter=…` question
+    # prints the same files' text and writes nothing.
     module ProjectDiagrams
       module_function
 
@@ -15,7 +16,7 @@ module Hecks
         chapter_name = argv[1] or abort usage
 
         runtime   = Hecks.boot(File.expand_path(domain_path, Dir.pwd))
-        chapter   = runtime.registry.bluebook(chapter_name)
+        chapter   = runtime.registry.bluebook(chapter_name) or abort "no chapter named #{chapter_name}"
         hecksagon = runtime.registry.hecksagon(chapter_name)
         directory = File.expand_path("docs/generated/diagrams/#{Naming.snake(chapter_name)}", root)
 

data/lib/hecks/cli/project_glossary.rb

@@ -0,0 +1,44 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `hecks glossary`: boots a domain and projects one chapter into its
+    # Ubiquitous Language glossary, `glossary.md` plus `html/index.html` rendered from it, in the
+    # domain's own `glossary/` folder.
+    #
+    # A field the deployment marks sensitive (`has_phi(readable_by:)` in the domain's `.hecksagon`)
+    # is tagged in the glossary with its category. spec/glossary_spec.rb re-projects every one and
+    # refuses a diff, so a committed glossary never lags the bluebook it describes.
+    module ProjectGlossary
+      module_function
+
+      # Writes the chapter's glossary and prints each file written.
+      #
+      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param program [String] the name the usage line shows
+      # @return [void]
+      # @raise [SystemExit] with the usage line when an argument is missing
+      def call(argv, program: "hecks glossary")
+        usage = "usage: #{program} <domain-path> <ChapterName>"
+        domain_path  = argv[0] or abort usage
+        chapter_name = argv[1] or abort usage
+
+        domain  = File.expand_path(domain_path, Dir.pwd)
+        runtime = Hecks.boot(domain)
+        chapter = runtime.registry.bluebook(chapter_name)
+
+        markings = runtime.registry.pending_privacy_markings.select do |marking|
+          marking[:domain].to_s.start_with?("#{chapter_name}::")
+        end
+
+        written = Projector.write(
+          Projector.call(:glossary, bluebook: chapter, options: { markings: markings }),
+          File.join(domain, "glossary"), as: :files
+        )
+
+        puts "wrote #{written.size} file(s):"
+        written.each { |path| puts "  #{path}" }
+      end
+    end
+  end
+end

data/lib/hecks/cli/reference.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../projection_files"
+
+module Hecks
+  module CLI
+    # The command behind `hecks project_reference`: regenerates `docs/implemented/reference/` from
+    # the language's Syntax chapter. Tables come from the declaration; prose is kept from the
+    # committed pages.
+    module Reference
+      module_function
+
+      # Writes the pages and reports both coverage gates together (`DocCoverage` asks the same
+      # as an exit status).
+      #
+      # @param root [String] the repository root
+      # @param out [IO] where the report goes
+      # @return [Integer] the exit status, always 0
+      def call(root:, out: $stdout)
+        directory = File.join(root, "docs/implemented/reference")
+        written = Hecks::ProjectionFiles.write(:reference, root: root)
+        out.puts "wrote #{written.size - 1} pages to docs/implemented/reference/, " \
+                 "and regenerated README.md's own indexes"
+        { "prose"             => Hecks::Doc::Reference.undocumented(directory),
+          "a running example" => Hecks::Doc::Reference.unexemplified(directory) }.each do |owed, missing|
+          report(out, owed, missing)
+        end
+        0
+      end
+
+      # @param out [IO] where the line goes
+      # @param owed [String] what each word owes: prose, or a running example
+      # @param missing [Array<String>] the words that lack it
+      # @return [void]
+      def report(out, owed, missing)
+        if missing.empty?
+          out.puts "every live word carries #{owed}."
+        else
+          out.puts "#{missing.size} word(s) still carry no #{owed}:"
+          missing.each { |word| out.puts "  #{word}" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/refresh_projections.rb

@@ -0,0 +1,44 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The logic behind `hecks refresh_projections` and Custodian's `Operation.RefreshProjections`:
+    # forces every
+    # read-model projection a booted domain declares to catch up now, the same catch-up a boot
+    # runs lazily on first read.
+    module RefreshProjections
+      module_function
+
+      # Boots the domain `argv` names and refreshes its projections, as `hecks refresh_projections`
+      # does.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the usage message calls this command by
+      # @return [Integer] 0
+      # @raise [SystemExit] when `argv` is empty
+      def run(argv, program: "hecks refresh_projections")
+        domain = argv.first or abort "usage: #{program} <domain>"
+        call(Hecks.boot(domain))
+        0
+      end
+
+      # Refreshes every projection of every chapter in a booted runtime.
+      #
+      # @param runtime [Runtime] a booted domain
+      # @return [Integer] how many projections were caught up
+      def call(runtime)
+        refreshed = 0
+        runtime.registry.bluebooks.each do |domain, bluebook|
+          bluebook.aggregates.each do |aggregate|
+            worker = Ports::Projection.worker(runtime.registry, domain, aggregate, policy: :refresh)
+            next unless worker
+
+            worker.catch_up!
+            refreshed += 1
+          end
+        end
+        refreshed
+      end
+    end
+  end
+end